Skip to content

README.md

Latest commit

 

History

History
167 lines (125 loc) · 6.59 KB

README.md

File metadata and controls

167 lines (125 loc) · 6.59 KB
Raw

Go Micro Examples

This directory contains runnable examples that take you through the Go Micro lifecycle: start with a service, expose it as agent-usable capability, then coordinate work with workflows.

Quick Start

Each example can be run with go run . from its directory unless its README says otherwise. If you are new to the repo, follow the first-agent path below instead of reading the directories alphabetically.

Recommended first-agent path

This path is the canonical services → agents → workflows route through the examples map. Debugging and observability wayfinding stays nearby once the first run works.

Step Start here What you learn Next step
1. First service hello-world Build the 0→1 service path: create and register a basic RPC service, add a handler, call it with a client, and expose health checks. Move to agent-demo to see services used by an agent.
2. First agent first-agent Run the smallest service-backed agent with a deterministic mock model and no provider key. Compare with agent-demo or the maintained 0-to-hero path in support.
3. First workflow support Follow typed services into an agent chat loop, an event-driven intake flow, and an approval gate in one runnable reference. Deepen the workflow model with flow-durable.

For the shortest AI-tooling bridge, the MCP path is mcp/hello → mcp/crud → mcp/workflow. For debugging and production hardening, keep agent-wrap-tool, agent-durable, and deployment nearby.

Lifecycle map

1. Services — learn the runtime foundation

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

2. Agents — turn services into tool-using teammates

first-agent

Smallest first agent: one notes service plus one scoped agent, backed by a deterministic mock model so go run ./examples/first-agent works without provider secrets.

agent-demo

A multi-service project management app with Projects, Tasks, and Team services, 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

agent-durable

Durable agent runs that can be checkpointed and resumed, useful once your first agent needs predictable recovery behavior.

agent-human-input

Human-in-the-loop agent interaction for decisions that need an explicit person before the run can continue.

agent-ollama

Local-model agent wiring for developers experimenting with Ollama-backed model calls.

3. Workflows — coordinate longer-running work

support

A maintained 0-to-hero reference path in one runnable file:

  • scaffold typed customers, tickets, and notify services
  • run/chat with a support agent that uses those services as tools
  • inspect the event-driven intake flow and approval gate
  • CI keeps the deterministic mock-model journey runnable with go test ./examples/support

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)

flow-loop

A looping flow example for repeated workflow steps.

4. MCP and agent integration 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
  • platform - Platform-oriented MCP service example

Other examples

auth

Authentication and authorization example.

graceful-stop

Graceful shutdown behavior for long-running services.

grpc-interop

gRPC interoperability example.

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:

  1. Create a new directory
  2. Add a descriptive README.md
  3. Include working code with comments
  4. Add to this index under the lifecycle stage it supports
  5. Ensure it runs with go run .