micro--go-micro
Asim Aslam
9fdcc24cce
* docs: design note for flow steps + Checkpoint durable execution
* docs: fold in durable-execution decisions (State struct, single Step, run retention, retry)
* docs: rename State.Payload to State.Data
* feat(flow): ordered steps + Checkpoint durable execution
A flow can now be an ordered list of steps (a task with stages) instead
of a single LLM turn. State carries typed Data plus a Stage marker; each
step is checkpointed before and after via a pluggable Checkpoint
(store-backed by default), so a run survives a crash and resumes where it
stopped without re-running completed steps. Flow-level Retry with a
per-step override; runs retained for audit unless DeleteOnSuccess.
Step actions: Call (RPC), LLM (augmented turn), Dispatch (to an agent),
or any StepFunc. Single-step and agent-dispatch flows are unchanged.
* feat(flow): top-level re-exports + durable flow example
Expose the step/checkpoint API from the micro package (FlowSteps,
FlowStep, FlowState, FlowRetry, FlowWithCheckpoint, FlowCall/LLM/Dispatch,
Checkpoint, StoreCheckpoint) and add a runnable, key-free example
demonstrating crash + resume.
* docs: document durable flow steps (guide, README, CLI help)
* docs: blog post + changelog for durable workflows
* fix(flow): scope checkpoint keys by flow name (flow/{name}/runs/{id})
Run keys were flow/runs/{id} — a single global keyspace shared by every
flow on the default store. Namespace them by flow name so each flow's
state is kept apart. StoreCheckpoint now takes a scope argument (the flow
passes its name by default).
* feat(store): Scope handle; scope agent and flow state by name
Add store.Scope(s, database, table) — a store handle that confines every
operation to a database/table without mutating the shared store, so
co-located components don't clobber each other's table (the failure mode
of the global Init(Table(...)) approach).
Use it to keep each agent's memory and plan in its own table
(agent/{name}) and each flow's runs in its own (flow/{name}), instead of
one global table partitioned only by key prefix. Services already scope
by service name.
* feat: consistent state model — service store scoping, flow registry, list/history CLI
- service: scope store via store.Scope (database service / table name),
retiring the Init(store.Table(name)) global-mutation hack; bridge the
default store so handlers using store.DefaultStore stay isolated.
- flow: register in the registry as type=flow while running (with trigger
and step count), deregister on Stop. Live discovery, like agents.
- cli: micro flow list (registry), micro flow runs <name> (durable store),
micro agent history <name> (durable store). list = running, runs/history
= durable, mirroring the service model.
* test: mini-universe end-to-end harness + scheduled GitHub Action
internal/harness/universe boots a small but real go-micro world — four
services, a durable checkout flow that crashes at payment and resumes,
and a guardrailed agent with a tool wrapper reached over RPC — drives the
scenario, asserts the end state (10 checks), and shuts down. Everything
is real except the LLM (mocked), so it's deterministic and needs no key;
-provider anthropic runs it live. Exits non-zero on failure, so it's an
end-to-end test, not just a demo.
Adds .github/workflows/universe.yml (push/PR/daily/dispatch) running the
universe + existing harnesses on the mock provider, plus an opt-in job
that runs live when ANTHROPIC_API_KEY is set. 'make harness' runs them
locally.
* ci: run the live universe job against AtlasCloud (ATLASCLOUD_API_KEY)
* ci: run the live universe job only on schedule or manual dispatch
The deterministic mock job still runs on push/PR/daily; the live
(AtlasCloud) job runs daily and on manual workflow_dispatch only, so
changes don't burn API credits on every PR but can still be checked
against a real model on demand.
---------
Co-authored-by: Claude <noreply@anthropic.com>
Go Micro Examples
This directory contains runnable examples demonstrating various go-micro features and patterns.
Quick Start
Each example can be run with go run . from its directory.
Examples
hello-world
Basic RPC service demonstrating core concepts:
- Service creation and registration
- Handler implementation
- Client calls
- Health checks
Run it:
cd hello-world
go run .
web-service
HTTP web service with service discovery:
- HTTP handlers
- Service registration
- Health checks
- JSON REST API
Run it:
cd web-service
go run .
multi-service
Multiple services in a single binary — the modular monolith pattern:
- Isolated server, client, store, and cache per service
- Shared registry and broker for inter-service communication
- Coordinated lifecycle with
service.Group - Start monolith, split later when you need to scale independently
Run it:
cd multi-service
go run .
deployment
Docker Compose deployment with MCP gateway, Consul registry, and Jaeger tracing:
- Production-like architecture in one
docker-compose up - Standalone MCP gateway connected to service registry
- Distributed tracing with OpenTelemetry + Jaeger
MCP Examples
See the mcp/ directory for AI agent integration examples:
- hello - Minimal MCP service (start here)
- crud - CRUD contact book with full agent documentation
- workflow - Cross-service orchestration via AI agents
- documented - All MCP features with auth scopes
agent-demo
Multi-service project management app (Projects, Tasks, Team) with seed data and agent playground integration.
agent-plan-delegate
The two built-in agent capabilities in a small multi-agent system:
- plan — an agent records an ordered plan in its store-backed memory before doing multi-step work
- delegate — an agent hands a subtask to another agent (over RPC if it's registered, else to an ephemeral sub-agent)
agent-wrap-tool
Middleware around an agent's tool execution with AgentWrapTool, the tool-side analogue of client/server wrappers:
- observe — time every tool call and record per-tool metrics, correlated by call ID
- retry — re-run a call whose result is an error, recovering from a transient failure before the model sees it
flow-durable
A workflow as ordered, checkpointed steps that survives a crash and resumes where it stopped:
- steps — a flow is a task with stages (
reserve → charge → confirm), not just one LLM turn - Checkpoint — each step is persisted; on
Resume, completed steps are not re-run (no duplicate side effects)
Coming Soon
- pubsub-events - Event-driven architecture with NATS
- grpc-integration - Using go-micro with gRPC
Prerequisites
Some examples require external dependencies:
- NATS:
docker run -p 4222:4222 nats:latest - Consul:
docker run -p 8500:8500 consul:latest agent -dev -ui -client=0.0.0.0 - Redis:
docker run -p 6379:6379 redis:latest
Contributing
To add a new example:
- Create a new directory
- Add a descriptive README.md
- Include working code with comments
- Add to this index
- Ensure it runs with
go run .