Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Codex
|
b21f8a47aa |
@@ -21,8 +21,8 @@ changes, architectural rewrites. Those go to the human.
|
||||
|
||||
## Work queue (ranked)
|
||||
|
||||
1. **Make plan-delegate notification side effects idempotent** ([#4100](https://github.com/micro/go-micro/issues/4100)) — the latest live provider-conformance run exposed a duplicate delegated notify call in the plan-delegate harness. Fixing this protects the green-CI evaluator and the services → agents → workflows contract: model retries or repeated tool attempts must not create duplicate real side effects. Keep the patch narrow around the harness/service boundary and add a deterministic replay test before relying on the next live atlascloud run.
|
||||
2. **Unify first-agent run inspection command across CLI and docs** ([#4104](https://github.com/micro/go-micro/issues/4104)) — the install, first-agent, debugging, and 0→hero on-ramp is now rich enough that command-name drift becomes the next adoption seam. Make the documented inspect step copy/pasteable from the CLI and website, either by adding the intended alias or aligning docs on the existing command, and guard the CLI/docs boundary with focused tests.
|
||||
1. **Keep website quickstart on the first-agent on-ramp** ([#4071](https://github.com/micro/go-micro/issues/4071)) — the README, Getting Started guide, docs index, examples map, CLI docs, and zero-to-hero guide now tell the provider-free first-agent story in order; the website Quick Start page still trails that canonical path by omitting some wayfinding anchors (`micro agent demo`, the no-secret transcript, debugging/inspect). Update the page and extend the focused docs harness so quickstart drift fails fast. This keeps developer adoption weighted alongside hardening instead of letting the queue become purely internal.
|
||||
2. **Add install troubleshooting to the first-agent on-ramp** ([#4077](https://github.com/micro/go-micro/issues/4077)) — after the quickstart page is aligned, close the next 0→1 adoption seam: install verification and recovery before a newcomer reaches `micro new` or `micro agent demo`. Link a focused install troubleshooting path from the canonical on-ramp pages, cover binary installer versus `go install`, PATH/version checks, and the no-secret smoke path, then add a docs harness assertion so the install-recovery link cannot drift out of the first-agent journey.
|
||||
|
||||
_Seeded by Claude Code from the roadmap + open issues; thereafter maintained by the
|
||||
architecture-review pass._
|
||||
|
||||
@@ -50,8 +50,6 @@ curl -fsSL https://go-micro.dev/install.sh | sh
|
||||
go install go-micro.dev/v6/cmd/micro@latest
|
||||
```
|
||||
|
||||
If install or `PATH` checks fail, use the [install troubleshooting guide](internal/website/docs/guides/install-troubleshooting.md) before scaffolding your first service.
|
||||
|
||||
### Fastest start — no API key
|
||||
|
||||
Scaffold a service, run it, call it:
|
||||
@@ -89,18 +87,16 @@ make harness
|
||||
After install and the first `micro new`/`micro run` smoke check, take the
|
||||
walkable agent path in this order:
|
||||
|
||||
1. [Install troubleshooting](internal/website/docs/guides/install-troubleshooting.md) — verify the binary installer or `go install`, `PATH`, `micro --version`, and the no-secret smoke path before agent work.
|
||||
2. `micro agent demo` — print the provider-free first-agent demo command and next docs steps from the installed CLI.
|
||||
3. `micro zero-to-hero` — print the maintained one-command no-secret lifecycle harness and runnable examples.
|
||||
4. [Smallest first-agent example](examples/first-agent/) — run one service-backed agent with a mock model and no provider key.
|
||||
5. [No-secret first-agent transcript](internal/website/docs/guides/no-secret-first-agent.md) — run the
|
||||
1. `micro agent demo` — print the provider-free first-agent demo command and next docs steps from the installed CLI.
|
||||
2. [Smallest first-agent example](examples/first-agent/) — run one service-backed agent with a mock model and no provider key.
|
||||
3. [No-secret first-agent transcript](internal/website/docs/guides/no-secret-first-agent.md) — run the
|
||||
maintained support agent with a mock model and see services → agents → workflows succeed without a key.
|
||||
6. [Your First Agent](internal/website/docs/guides/your-first-agent.md) — build a
|
||||
4. [Your First Agent](internal/website/docs/guides/your-first-agent.md) — build a
|
||||
service-backed agent and talk to it with `micro chat`.
|
||||
7. [Debugging your agent](internal/website/docs/guides/debugging-agents.md) — use
|
||||
5. [Debugging your agent](internal/website/docs/guides/debugging-agents.md) — use
|
||||
`micro agent inspect`, run history, memory, and provider checks when the first
|
||||
conversation does something unexpected.
|
||||
8. [0→hero Reference](internal/website/docs/guides/zero-to-hero.md) — complete the
|
||||
6. [0→hero Reference](internal/website/docs/guides/zero-to-hero.md) — complete the
|
||||
services → agents → workflows loop with scaffold, run, chat, inspect, flow
|
||||
history, and deploy dry-run commands that match the maintained harness.
|
||||
|
||||
|
||||
@@ -33,10 +33,9 @@ After it passes:
|
||||
- Walk the full 0→hero lifecycle: https://go-micro.dev/docs/guides/zero-to-hero.html
|
||||
|
||||
Use live-provider chat when you are ready for real model behavior:
|
||||
micro agent preflight # before micro run: prerequisites
|
||||
micro agent preflight
|
||||
micro run
|
||||
micro chat
|
||||
micro agent doctor # after micro run: chat/gateway/inspect recovery
|
||||
micro inspect agent <name>`
|
||||
|
||||
func init() {
|
||||
@@ -81,7 +80,7 @@ for live-provider chat and inspect/debugging.`,
|
||||
},
|
||||
{
|
||||
Name: "doctor",
|
||||
Usage: "Diagnose chat, gateway, registration, provider, and inspect recovery after micro run",
|
||||
Usage: "Diagnose chat and inspect recovery after micro run",
|
||||
Flags: []cli.Flag{
|
||||
&cli.StringFlag{Name: "gateway", Value: "http://localhost:8080", Usage: "Gateway URL started by micro run"},
|
||||
},
|
||||
|
||||
+2
-35
@@ -24,28 +24,6 @@ import (
|
||||
_ "go-micro.dev/v6/cmd/micro/cli/remote"
|
||||
)
|
||||
|
||||
const zeroToHeroHelp = `0→hero no-secret lifecycle demo
|
||||
|
||||
Run this from a go-micro repository checkout when you want one command that
|
||||
proves the maintained services → agents → workflows path without provider keys:
|
||||
|
||||
./internal/harness/zero-to-hero-ci/run.sh
|
||||
|
||||
That script runs the same deterministic path CI uses:
|
||||
- CLI discovery for scaffold, run, chat, inspect, flow runs, and deploy dry-run
|
||||
- the smallest first-agent example
|
||||
- the support-desk reference app with services, an agent, a flow, and an approval gate
|
||||
- plan/delegate and universe harnesses with only the model mocked
|
||||
|
||||
If you only want the runnable examples first:
|
||||
go run ./examples/first-agent
|
||||
go run ./examples/support
|
||||
|
||||
Full local contract:
|
||||
make harness
|
||||
|
||||
Guide: https://go-micro.dev/docs/guides/zero-to-hero.html`
|
||||
|
||||
const docsWayfinding = `First-agent and 0→hero docs:
|
||||
|
||||
1. Start with the no-secret CLI demo
|
||||
@@ -62,10 +40,10 @@ const docsWayfinding = `First-agent and 0→hero docs:
|
||||
3. Your First Agent
|
||||
https://go-micro.dev/docs/guides/your-first-agent.html
|
||||
Build a service-backed agent, then use:
|
||||
micro agent preflight # before micro run: prerequisites
|
||||
micro agent preflight
|
||||
micro run
|
||||
micro chat
|
||||
micro agent doctor # after micro run: chat/gateway/inspect recovery
|
||||
micro agent doctor
|
||||
|
||||
4. Debugging your agent
|
||||
https://go-micro.dev/docs/guides/debugging-agents.html
|
||||
@@ -150,17 +128,6 @@ func init() {
|
||||
return nil
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "zero-to-hero",
|
||||
Usage: "Show the no-secret 0→hero lifecycle demo command",
|
||||
Description: `Print the maintained provider-free services → agents → workflows
|
||||
lifecycle command and the smaller runnable examples it covers.`,
|
||||
Aliases: []string{"hero"},
|
||||
Action: func(ctx *cli.Context) error {
|
||||
fmt.Fprintln(ctx.App.Writer, zeroToHeroHelp)
|
||||
return nil
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "docs",
|
||||
Usage: "Show the first-agent and 0→hero documentation path",
|
||||
|
||||
@@ -64,10 +64,10 @@ func TestFirstAgentWalkthroughCLIBoundaries(t *testing.T) {
|
||||
"your-first-agent.html",
|
||||
"debugging-agents.html",
|
||||
"zero-to-hero.html",
|
||||
"micro agent preflight # before micro run: prerequisites",
|
||||
"micro agent preflight",
|
||||
"micro run",
|
||||
"micro chat",
|
||||
"micro agent doctor # after micro run: chat/gateway/inspect recovery",
|
||||
"micro agent doctor",
|
||||
"micro inspect agent",
|
||||
} {
|
||||
if !strings.Contains(out.String(), want) {
|
||||
@@ -79,13 +79,6 @@ func TestFirstAgentWalkthroughCLIBoundaries(t *testing.T) {
|
||||
if !strings.Contains(agent.Usage, "micro agent demo") {
|
||||
t.Fatalf("micro agent help should advertise the no-secret demo; usage was %q", agent.Usage)
|
||||
}
|
||||
doctor := subcommandByName(t, agent, "doctor")
|
||||
for _, want := range []string{"chat", "gateway", "registration", "provider", "inspect", "after micro run"} {
|
||||
if !strings.Contains(doctor.Usage, want) {
|
||||
t.Fatalf("micro agent doctor usage should advertise after-run recovery for %q; usage was %q", want, doctor.Usage)
|
||||
}
|
||||
}
|
||||
|
||||
demo := subcommandByName(t, agent, "demo")
|
||||
out.Reset()
|
||||
if err := demo.Action(cli.NewContext(app, nil, nil)); err != nil {
|
||||
@@ -95,9 +88,8 @@ func TestFirstAgentWalkthroughCLIBoundaries(t *testing.T) {
|
||||
"No-secret first-agent demo",
|
||||
"go test ./internal/harness/zero-to-hero-ci -run TestNoSecretFirstAgentTranscript -count=1",
|
||||
"provider-free",
|
||||
"micro agent preflight # before micro run: prerequisites",
|
||||
"micro agent preflight",
|
||||
"micro chat",
|
||||
"micro agent doctor # after micro run: chat/gateway/inspect recovery",
|
||||
"micro inspect agent <name>",
|
||||
"your-first-agent.html",
|
||||
"debugging-agents.html",
|
||||
|
||||
@@ -1,8 +1,6 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
microcmd "go-micro.dev/v6/cmd"
|
||||
@@ -21,7 +19,7 @@ func TestZeroToHeroCLIBoundaries(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
for _, want := range []string{"run", "chat", "flow", "inspect", "deploy", "zero-to-hero"} {
|
||||
for _, want := range []string{"run", "chat", "flow", "inspect", "deploy"} {
|
||||
if !commands[want] {
|
||||
t.Fatalf("missing %q command", want)
|
||||
}
|
||||
@@ -50,29 +48,3 @@ func TestZeroToHeroCLIBoundaries(t *testing.T) {
|
||||
t.Fatal("missing deploy boundary: deploy --dry-run")
|
||||
}
|
||||
}
|
||||
|
||||
func TestZeroToHeroCommandPrintsMaintainedNoSecretPath(t *testing.T) {
|
||||
app := microcmd.DefaultCmd.App()
|
||||
var out bytes.Buffer
|
||||
oldWriter := app.Writer
|
||||
app.Writer = &out
|
||||
t.Cleanup(func() { app.Writer = oldWriter })
|
||||
|
||||
if err := app.Run([]string{"micro", "zero-to-hero"}); err != nil {
|
||||
t.Fatalf("micro zero-to-hero failed: %v", err)
|
||||
}
|
||||
|
||||
got := out.String()
|
||||
for _, want := range []string{
|
||||
"0→hero no-secret lifecycle demo",
|
||||
"./internal/harness/zero-to-hero-ci/run.sh",
|
||||
"go run ./examples/first-agent",
|
||||
"go run ./examples/support",
|
||||
"make harness",
|
||||
"services → agents → workflows",
|
||||
} {
|
||||
if !strings.Contains(got, want) {
|
||||
t.Fatalf("micro zero-to-hero output missing %q:\n%s", want, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -21,7 +21,6 @@ func TestZeroToHeroReferenceDocs(t *testing.T) {
|
||||
"go test ./examples/first-agent -run TestRunFirstAgent -count=1",
|
||||
"go test ./examples/support -run 'TestRunSupportMockSmoke|TestZeroToHeroReadmeDocumentsLifecycle' -count=1",
|
||||
"./internal/harness/zero-to-hero-ci/run.sh",
|
||||
"micro zero-to-hero",
|
||||
"go run ./internal/harness/agent-flow",
|
||||
"make provider-conformance-mock",
|
||||
"internal/harness/plan-delegate",
|
||||
@@ -77,41 +76,6 @@ func TestGuidesNavigationLeadsWithDoing(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
func TestArchitectureDocsAlignWithAgentHarnessLifecycle(t *testing.T) {
|
||||
root := filepath.Clean(filepath.Join("..", "..", ".."))
|
||||
doc := readFile(t, filepath.Join(root, "internal", "website", "docs", "architecture.md"))
|
||||
|
||||
for _, want := range []string{
|
||||
"services → agents → workflows lifecycle",
|
||||
"## Service substrate",
|
||||
"## Agent harness",
|
||||
"## Workflows",
|
||||
"## Interop gateways",
|
||||
"`model` / `ai.Model`",
|
||||
"`store` / memory",
|
||||
"`ai.Tools`",
|
||||
"`agent`",
|
||||
"`flow`",
|
||||
"`micro mcp`",
|
||||
"`micro a2a`",
|
||||
"[AI Integration](ai-integration.html)",
|
||||
"[Your First Agent](guides/your-first-agent.html)",
|
||||
"[0→hero Reference](guides/zero-to-hero.html)",
|
||||
} {
|
||||
if !strings.Contains(doc, want) {
|
||||
t.Fatalf("architecture doc missing lifecycle marker %q", want)
|
||||
}
|
||||
}
|
||||
|
||||
assertOrderedMarkers(t, "architecture lifecycle", doc, []string{
|
||||
"## Service substrate",
|
||||
"## Agent harness",
|
||||
"## Workflows",
|
||||
"## Interop gateways",
|
||||
"## Developer path",
|
||||
})
|
||||
}
|
||||
|
||||
func TestFirstAgentWayfindingDocs(t *testing.T) {
|
||||
root := filepath.Clean(filepath.Join("..", "..", ".."))
|
||||
checks := []struct {
|
||||
@@ -125,9 +89,7 @@ func TestFirstAgentWayfindingDocs(t *testing.T) {
|
||||
file: filepath.Join(root, "README.md"),
|
||||
heading: "### First agent on-ramp",
|
||||
links: []string{
|
||||
"internal/website/docs/guides/install-troubleshooting.md",
|
||||
"micro agent demo",
|
||||
"micro zero-to-hero",
|
||||
"internal/website/docs/guides/no-secret-first-agent.md",
|
||||
"internal/website/docs/guides/your-first-agent.md",
|
||||
"internal/website/docs/guides/debugging-agents.md",
|
||||
@@ -169,9 +131,7 @@ func TestFirstAgentWayfindingDocs(t *testing.T) {
|
||||
file: filepath.Join(root, "internal", "website", "docs", "getting-started.md"),
|
||||
heading: "### First-agent on-ramp",
|
||||
links: []string{
|
||||
"guides/install-troubleshooting.html",
|
||||
"micro agent demo",
|
||||
"micro zero-to-hero",
|
||||
"guides/no-secret-first-agent.html",
|
||||
"guides/your-first-agent.html",
|
||||
"guides/debugging-agents.html",
|
||||
@@ -370,7 +330,6 @@ func TestGettingStartedDocsLeadWithNoSecretFirstRun(t *testing.T) {
|
||||
file: filepath.Join(root, "README.md"),
|
||||
section: "## Quick Start",
|
||||
want: []string{
|
||||
"install troubleshooting guide",
|
||||
"### Fastest start — no API key",
|
||||
"micro new helloworld",
|
||||
"micro run",
|
||||
@@ -395,9 +354,8 @@ func TestGettingStartedDocsLeadWithNoSecretFirstRun(t *testing.T) {
|
||||
{
|
||||
name: "website getting started",
|
||||
file: filepath.Join(root, "internal", "website", "docs", "getting-started.md"),
|
||||
section: "Install troubleshooting",
|
||||
section: "## Quick Start: Scaffold, Run, Call",
|
||||
want: []string{
|
||||
"Install troubleshooting",
|
||||
"## Quick Start: Scaffold, Run, Call",
|
||||
"micro new helloworld",
|
||||
"micro run",
|
||||
@@ -407,22 +365,6 @@ func TestGettingStartedDocsLeadWithNoSecretFirstRun(t *testing.T) {
|
||||
"## Generate from a Prompt — with an LLM key",
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "website quickstart",
|
||||
file: filepath.Join(root, "internal", "website", "docs", "quickstart.md"),
|
||||
section: "## Create Your First Service",
|
||||
want: []string{
|
||||
"micro new helloworld",
|
||||
"micro run",
|
||||
"curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call",
|
||||
"## Next Steps",
|
||||
"micro agent demo",
|
||||
"micro zero-to-hero",
|
||||
"guides/no-secret-first-agent.html",
|
||||
"guides/debugging-agents.html",
|
||||
"guides/zero-to-hero.html",
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
for _, check := range checks {
|
||||
|
||||
@@ -3,8 +3,6 @@ core:
|
||||
url: /docs/
|
||||
- title: Getting Started
|
||||
url: /docs/getting-started.html
|
||||
- title: Install Troubleshooting
|
||||
url: /docs/guides/install-troubleshooting.html
|
||||
- title: AI Integration
|
||||
url: /docs/ai-integration.html
|
||||
- title: No-secret First Agent
|
||||
@@ -82,7 +80,6 @@ project:
|
||||
- title: Server (optional)
|
||||
url: /docs/server.html
|
||||
search_order:
|
||||
- /docs/guides/install-troubleshooting.html
|
||||
- /docs/guides/your-first-agent.html
|
||||
- /docs/guides/zero-to-hero.html
|
||||
- /docs/guides/debugging-agents.html
|
||||
|
||||
@@ -2,124 +2,75 @@
|
||||
layout: default
|
||||
---
|
||||
|
||||
# Architecture
|
||||
## Architecture
|
||||
|
||||
<img src="/images/generated/architecture.jpg" alt="Go Micro architecture" style="width: 100%; border-radius: 8px; margin: 1rem 0 1.5rem;" />
|
||||
|
||||
Go Micro is one runtime for the services → agents → workflows lifecycle. The same
|
||||
registry, client/server RPC, store, broker, and gateway primitives that run a
|
||||
service also give an agent discoverable tools, durable state, interop, and a
|
||||
place to hand off deterministic work.
|
||||
An overview of the Go Micro architecture.
|
||||
|
||||
## Lifecycle map
|
||||
## Overview
|
||||
|
||||
```text
|
||||
Services → Agents → Workflows
|
||||
handlers model loop durable orchestration
|
||||
registry memory triggers and ordered steps
|
||||
RPC tools guardrails agent dispatch
|
||||
```
|
||||
Go Micro abstracts away the details of distributed systems. Here are the main features.
|
||||
|
||||
The layers are progressive: start with a service, expose its endpoints as tools,
|
||||
wrap those tools with an agent, then move the known paths into flows so the model
|
||||
only handles the uncertain parts.
|
||||
- **Authentication** - Auth is built in as a first class citizen. Authentication and authorization enable secure
|
||||
zero trust networking by providing every service an identity and certificates. This additionally includes rule
|
||||
based access control.
|
||||
|
||||
## Service substrate
|
||||
- **Dynamic Config** - Load and hot reload dynamic config from anywhere. The config interface provides a way to load application
|
||||
level config from any source such as env vars, file, etcd. You can merge the sources and even define fallbacks.
|
||||
|
||||
Go Micro's service framework supplies the distributed-systems base every agent
|
||||
needs:
|
||||
- **Data Storage** - A simple data store interface to read, write and delete records. It includes support for many storage backends
|
||||
in the plugins repo. State and persistence becomes a core requirement beyond prototyping and Micro looks to build that into the framework.
|
||||
|
||||
- **Registry** — services, agents, and flows register under names so clients,
|
||||
gateways, and other agents can discover them without hard-coded addresses. The
|
||||
default is mDNS for local development, with pluggable backends for production.
|
||||
- **RPC client/server** — endpoints are normal Go handlers reached through the
|
||||
client, load balanced through discovery, encoded through codecs, and optionally
|
||||
streamed.
|
||||
- **Broker** — asynchronous events connect services and trigger flows without
|
||||
coupling producers to consumers.
|
||||
- **Config and auth** — dynamic configuration plus identity and authorization keep
|
||||
local and production runtimes using the same shape.
|
||||
- **Pluggable interfaces** — registry, broker, store, transport, codecs, auth, and
|
||||
config are Go interfaces, so the runtime can stay stable while deployments swap
|
||||
infrastructure.
|
||||
- **Service Discovery** - Automatic service registration and name resolution. Service discovery is at the core of micro service
|
||||
development. When service A needs to speak to service B it needs the location of that service. The default discovery mechanism is
|
||||
multicast DNS (mdns), a zeroconf system.
|
||||
|
||||
That substrate is intentionally not separate from the agent stack. A service
|
||||
endpoint is the smallest useful unit of work, and the registry is the source of
|
||||
truth for which tools and agents exist.
|
||||
- **Load Balancing** - Client side load balancing built on service discovery. Once we have the addresses of any number of instances
|
||||
of a service we now need a way to decide which node to route to. We use random hashed load balancing to provide even distribution
|
||||
across the services and retry a different node if there's a problem.
|
||||
|
||||
## Agent harness
|
||||
- **Message Encoding** - Dynamic message encoding based on content-type. The client and server will use codecs along with content-type
|
||||
to seamlessly encode and decode Go types for you. Any variety of messages could be encoded and sent from different clients. The client
|
||||
and server handle this by default. This includes protobuf and json by default.
|
||||
|
||||
Agents compose the service substrate with the AI-specific packages:
|
||||
- **RPC Client/Server** - RPC based request/response with support for bidirectional streaming. We provide an abstraction for synchronous
|
||||
communication. A request made to a service will be automatically resolved, load balanced, dialled and streamed.
|
||||
|
||||
- **`model` / `ai.Model`** — a pluggable model interface normalizes provider calls
|
||||
while letting applications pick Anthropic, OpenAI, Gemini, Atlas Cloud, Groq,
|
||||
Mistral, Together AI, or a mock model for no-secret tests.
|
||||
- **`store` / memory** — agent history, plans, run state, and compacted memory live
|
||||
in durable storage rather than in an in-process chat loop.
|
||||
- **`ai.Tools`** — discovers registered service endpoints and executes them through
|
||||
the Go Micro client, so tools are generated from running services instead of a
|
||||
parallel tool registry.
|
||||
- **`agent`** — runs the tool-calling loop with guardrails, planning, delegation,
|
||||
service-backed memory, and an `Agent.Chat` RPC endpoint. An agent is therefore a
|
||||
service other clients and agents can call.
|
||||
- **Async Messaging** - PubSub is built in as a first class citizen for asynchronous communication and event driven architectures.
|
||||
Event notifications are a core pattern in micro service development. The default messaging system is a HTTP event message broker.
|
||||
|
||||
The result is a harness, not just a prompt loop: model calls are bounded by tool
|
||||
scope, state is recoverable, and the same CLI and gateways that reach services can
|
||||
reach agents.
|
||||
- **Pluggable Interfaces** - Go Micro makes use of Go interfaces for each distributed system abstraction. Because of this these interfaces
|
||||
are pluggable and allows Go Micro to be runtime agnostic. You can plugin any underlying technology.
|
||||
|
||||
## Workflows
|
||||
## Design
|
||||
|
||||
Use `flow` when the path is known or must be repeatable. Flows subscribe to broker
|
||||
events, run ordered deterministic steps, and can dispatch to an agent at the point
|
||||
where judgment or language understanding is needed. This keeps long-running work
|
||||
observable and restartable while preserving agents for open-ended decisions.
|
||||
|
||||
A common shape is:
|
||||
|
||||
1. A service emits an event such as `ticket.created`.
|
||||
2. A flow validates and enriches the event with deterministic handlers.
|
||||
3. The flow dispatches to an agent for classification, drafting, or escalation.
|
||||
4. The agent calls registered service tools and returns to the flow for final
|
||||
durable steps.
|
||||
|
||||
## Interop gateways
|
||||
|
||||
Gateways project the same runtime to external callers:
|
||||
|
||||
- **`micro api`** exposes service RPC over HTTP.
|
||||
- **`micro mcp`** exposes registered service endpoints as Model Context Protocol
|
||||
tools for external agents.
|
||||
- **`micro a2a`** exposes registered Go Micro agents through the Agent2Agent
|
||||
protocol and lets Go Micro flows or agents dispatch to agents hosted elsewhere.
|
||||
|
||||
MCP is the services-as-tools boundary; A2A is the agents-as-agents boundary. Both
|
||||
come from registry metadata, so adding a service or agent updates the external
|
||||
surface without duplicate wiring.
|
||||
|
||||
## Developer path
|
||||
|
||||
If you are new, follow the architecture in the same order the runtime composes it:
|
||||
|
||||
1. [Install troubleshooting](guides/install-troubleshooting.html) — make sure the
|
||||
CLI, `PATH`, version, and no-secret smoke path are healthy.
|
||||
2. [`micro agent demo`](getting-started.html#first-agent-on-ramp) — print the
|
||||
provider-free first-agent command and next docs steps from the installed CLI.
|
||||
3. [Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent)
|
||||
— run one service-backed agent with a mock model.
|
||||
4. [No-secret first-agent transcript](guides/no-secret-first-agent.html) — see the
|
||||
maintained support-agent path work without a provider key.
|
||||
5. [Your First Agent](guides/your-first-agent.html) — build and chat with a
|
||||
service-backed agent.
|
||||
6. [Debugging your agent](guides/debugging-agents.html) — inspect service
|
||||
registration, tools, memory, providers, and run history.
|
||||
7. [0→hero Reference](guides/zero-to-hero.html) — walk scaffold → run → chat →
|
||||
inspect → flow → deploy dry-run as the maintained lifecycle contract.
|
||||
We will share more on architecture soon
|
||||
|
||||
## Related
|
||||
|
||||
- [AI Integration](ai-integration.html) — layer-by-layer services → agents → workflows wiring
|
||||
- [Getting Started](getting-started.html) — first service and first-agent on-ramp
|
||||
- [Examples](examples/) — runnable examples mapped to the lifecycle
|
||||
- [ADR Index](architecture/index.md) — architecture decision records
|
||||
- [ADR Index](architecture/index.md)
|
||||
- [Configuration](config.html)
|
||||
- [Plugins](plugins.html)
|
||||
|
||||
## Example Usage
|
||||
|
||||
Here's a minimal Go Micro service demonstrating the architecture:
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"go-micro.dev/v6"
|
||||
"log"
|
||||
)
|
||||
|
||||
func main() {
|
||||
service := micro.NewService("example",
|
||||
)
|
||||
service.Init()
|
||||
if err := service.Run(); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -29,8 +29,6 @@ curl -fsSL https://go-micro.dev/install.sh | sh
|
||||
go install go-micro.dev/v6/cmd/micro@latest
|
||||
```
|
||||
|
||||
If install or shell setup fails, start with [Install troubleshooting](guides/install-troubleshooting.html) to verify the binary installer or `go install`, `PATH`, `micro --version`, and the no-secret smoke path.
|
||||
|
||||
## Quick Start: Scaffold, Run, Call
|
||||
|
||||
Start with the path that proves the runtime works before any provider setup: install the CLI, scaffold one service, run it locally, then call it through the gateway.
|
||||
@@ -55,14 +53,12 @@ That install → scaffold → run → call loop is the 0→1 contract. It requir
|
||||
|
||||
After this quick start, follow the agent path in order:
|
||||
|
||||
1. [Install troubleshooting](guides/install-troubleshooting.html) — verify the CLI install before agent work.
|
||||
2. `micro agent demo` — print the provider-free first-agent demo command and next docs steps from the installed CLI.
|
||||
3. `micro zero-to-hero` — print the maintained one-command no-secret lifecycle harness and runnable examples.
|
||||
4. [Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent) — run one service-backed agent with a mock model and no provider key.
|
||||
5. [No-secret first-agent transcript](guides/no-secret-first-agent.html) — run a useful support agent with a mock model before setting up a provider key.
|
||||
6. [Your First Agent](guides/your-first-agent.html) — build a service-backed agent and talk to it with `micro chat`.
|
||||
7. [Debugging your agent](guides/debugging-agents.html) — inspect service registration, tool calls, run history, memory, provider failures, and flow handoffs when the agent surprises you.
|
||||
8. [0→hero reference path](guides/zero-to-hero.html) — prove the full scaffold → run → chat → inspect → deploy dry-run lifecycle with commands exercised by `make harness`.
|
||||
1. `micro agent demo` — print the provider-free first-agent demo command and next docs steps from the installed CLI.
|
||||
2. [Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent) — run one service-backed agent with a mock model and no provider key.
|
||||
3. [No-secret first-agent transcript](guides/no-secret-first-agent.html) — run a useful support agent with a mock model before setting up a provider key.
|
||||
4. [Your First Agent](guides/your-first-agent.html) — build a service-backed agent and talk to it with `micro chat`.
|
||||
5. [Debugging your agent](guides/debugging-agents.html) — inspect service registration, tool calls, run history, memory, provider failures, and flow handoffs when the agent surprises you.
|
||||
6. [0→hero reference path](guides/zero-to-hero.html) — prove the full scaffold → run → chat → inspect → deploy dry-run lifecycle with commands exercised by `make harness`.
|
||||
|
||||
## Write a Service
|
||||
|
||||
|
||||
@@ -17,21 +17,9 @@ micro inspect ... # read the recorded run or workflow history
|
||||
|
||||
Debug the lifecycle in the same order Go Micro runs it: first prove the service is
|
||||
registered and callable, then inspect the agent run that chose tools, then inspect
|
||||
any workflow that handed off to the agent.
|
||||
|
||||
Use the recovery command that matches where you are in the first-agent journey:
|
||||
|
||||
| Checkpoint | When to use it | Command |
|
||||
| --- | --- | --- |
|
||||
| Install troubleshooting | `micro` is not installed, not on `PATH`, or the shell cannot run it. | [Install troubleshooting](install-troubleshooting.html) |
|
||||
| Preflight before `micro run` | You have not started the local runtime yet and want to verify Go, CLI, provider-key, and gateway-port prerequisites. | `micro agent preflight` |
|
||||
| Doctor after `micro run` | `micro run` is active, but chat, the `/agent` gateway, agent registration, provider settings, or inspect/run history is not behaving. | `micro agent doctor` |
|
||||
|
||||
`micro agent preflight` is read-only and runs before the first local run; failed
|
||||
checks include `Fix:` and `Next:` lines for Go, CLI installation, provider-key
|
||||
setup, and the local gateway port. Once `micro run` is already up, switch to
|
||||
`micro agent doctor` so the recovery output follows the live gateway, chat
|
||||
settings, registered agents, provider configuration, and inspectable run history.
|
||||
any workflow that handed off to the agent. If the first local run fails before a
|
||||
chat turn, run `micro agent preflight`; failed checks include `Fix:` and `Next:`
|
||||
lines for Go, CLI installation, provider-key setup, and the local gateway port.
|
||||
|
||||
## 1. Reproduce one small turn
|
||||
|
||||
|
||||
@@ -1,96 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Install troubleshooting
|
||||
---
|
||||
|
||||
# Install troubleshooting
|
||||
|
||||
Use this page before `micro new` or `micro agent demo` when the CLI install is
|
||||
unclear. The goal is to prove three boundaries in order: the `micro` binary is on
|
||||
`PATH`, it is the version you expected, and the no-secret first-run path works
|
||||
without provider keys.
|
||||
|
||||
## 1. Choose one install path
|
||||
|
||||
### Binary installer (no Go required to install)
|
||||
|
||||
```sh
|
||||
curl -fsSL https://go-micro.dev/install.sh | sh
|
||||
```
|
||||
|
||||
Use this when you want the released `micro` binary without building it yourself.
|
||||
The generated services still need a Go toolchain when you run `micro run`, but the
|
||||
installer itself does not require Go.
|
||||
|
||||
### Go install (build from source)
|
||||
|
||||
```sh
|
||||
go install go-micro.dev/v6/cmd/micro@latest
|
||||
```
|
||||
|
||||
Use this when Go is already installed and you want the binary in your Go bin
|
||||
directory. If the command succeeds but `micro` is not found, your Go bin directory
|
||||
is probably not on `PATH`.
|
||||
|
||||
## 2. Verify `PATH` and version
|
||||
|
||||
Check which binary your shell will run:
|
||||
|
||||
```sh
|
||||
command -v micro
|
||||
micro --version
|
||||
```
|
||||
|
||||
If `command -v micro` prints nothing, add the install directory to `PATH`, then
|
||||
open a new terminal and retry. Common locations are:
|
||||
|
||||
```sh
|
||||
export PATH="$HOME/.micro/bin:$PATH" # binary installer
|
||||
export PATH="$(go env GOPATH)/bin:$PATH" # go install
|
||||
```
|
||||
|
||||
If `micro --version` shows an older binary than expected, remove the stale copy or
|
||||
put the intended install directory earlier in `PATH`.
|
||||
|
||||
## 3. Run the no-secret smoke path
|
||||
|
||||
Once `micro` resolves, prove the local service runtime before adding LLM provider
|
||||
keys:
|
||||
|
||||
```sh
|
||||
micro new helloworld
|
||||
cd helloworld
|
||||
micro run
|
||||
```
|
||||
|
||||
In another terminal:
|
||||
|
||||
```sh
|
||||
curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \
|
||||
-H 'Content-Type: application/json' -d '{"name":"World"}'
|
||||
```
|
||||
|
||||
This checks the scaffold, local build, gateway, and service registration without
|
||||
calling a model provider.
|
||||
|
||||
## 4. Recover common failures
|
||||
|
||||
| Symptom | Check | Fix |
|
||||
|---------|-------|-----|
|
||||
| `micro: command not found` | `command -v micro` | Add the installer bin directory or `$(go env GOPATH)/bin` to `PATH`, then open a new terminal. |
|
||||
| `micro run` cannot find Go | `go version` | Install Go 1.24 or newer from <https://go.dev/doc/install>. |
|
||||
| The gateway port is busy | `lsof -i :8080` | Stop the process using the port, or run with a different address. |
|
||||
| Provider-key errors block an agent run | `micro agent preflight` | Stay on the no-secret path first: run `micro agent demo`, then the no-secret first-agent guide. |
|
||||
|
||||
## 5. Continue the first-agent on-ramp
|
||||
|
||||
After install verification succeeds, continue in order:
|
||||
|
||||
1. `micro agent demo` — print the provider-free first-agent demo command and next docs steps.
|
||||
2. [No-secret first-agent transcript](no-secret-first-agent.html) — prove an agent can use services without a provider key.
|
||||
3. [Your First Agent](your-first-agent.html) — build and chat with your own service-backed agent.
|
||||
4. [Debugging your agent](debugging-agents.html) — inspect registration, tool calls, run history, and provider failures.
|
||||
5. [0→hero Reference](zero-to-hero.html) — walk the full services → agents → workflows lifecycle.
|
||||
|
||||
For repository contributors, `make install-smoke` runs the same installer seam
|
||||
against a local build without network access.
|
||||
@@ -53,11 +53,7 @@ Run the read-only first-agent preflight before starting the walkthrough. The sam
|
||||
micro agent preflight
|
||||
```
|
||||
|
||||
It checks Go 1.24+, the `micro` binary, provider-key setup, and the default local gateway port without contacting a provider. Failed checks include a `Fix:` line and a `Next:` line that points back to this guide, the no-secret walkthrough, or the debugging guide. Use it before `micro run`; if `micro run` is already active but `micro chat`, the `/agent` gateway, registration, provider settings, or inspect history is failing, run the after-run recovery check instead:
|
||||
|
||||
```sh
|
||||
micro agent doctor
|
||||
```
|
||||
It checks Go 1.24+, the `micro` binary, provider-key setup, and the default local gateway port without contacting a provider. Failed checks include a `Fix:` line and a `Next:` line that points back to this guide, the no-secret walkthrough, or the debugging guide.
|
||||
|
||||
## 1. Create a workspace
|
||||
|
||||
|
||||
@@ -28,16 +28,6 @@ cloud credentials?"
|
||||
| Runtime reference app | `examples/support` runs typed services, an agent using those services as tools, an event-driven flow handoff, and an approval gate with only the model mocked. | `go test ./examples/support -run 'TestRunSupportMockSmoke|TestZeroToHeroReadmeDocumentsLifecycle' -count=1` |
|
||||
| Runtime harnesses | Real services, agents, durable flows, store-backed history, delegation, and A2A run with only the model mocked. | `./internal/harness/zero-to-hero-ci/run.sh` and `make provider-conformance-mock` |
|
||||
|
||||
## Find the one-command entrypoint
|
||||
|
||||
After installing the CLI, ask `micro` for the maintained no-secret lifecycle command:
|
||||
|
||||
```sh
|
||||
micro zero-to-hero
|
||||
```
|
||||
|
||||
The command prints the exact harness command below plus the smaller runnable examples, so a new developer can discover the 0→hero path from CLI help instead of translating this guide by hand.
|
||||
|
||||
## Run the runnable example
|
||||
|
||||
From the repository root, start with the smallest service-backed agent when you want the fastest no-secret success path:
|
||||
|
||||
@@ -16,8 +16,6 @@ Or, if you have Go and prefer to build from source:
|
||||
go install go-micro.dev/v6/cmd/micro@latest
|
||||
```
|
||||
|
||||
If the installer finishes but your shell cannot find `micro`, open [Install troubleshooting](guides/install-troubleshooting.html) before creating your first service.
|
||||
|
||||
## Create Your First Service
|
||||
|
||||
```bash
|
||||
@@ -41,14 +39,10 @@ curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \
|
||||
|
||||
You now have the service half of the services → agents → workflows lifecycle running locally. Keep the on-ramp going in this order:
|
||||
|
||||
1. **[Install troubleshooting](guides/install-troubleshooting.html)** - verify the binary installer or `go install`, `PATH`, `micro --version`, and the no-secret smoke path.
|
||||
2. `micro agent demo` - print the provider-free first-agent demo command and the next docs steps from the installed CLI.
|
||||
3. `micro zero-to-hero` - print the maintained one-command no-secret lifecycle harness and runnable examples.
|
||||
4. **[Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent)** - run a mock-model, no-secret agent before adding provider keys.
|
||||
5. **[No-secret first-agent transcript](guides/no-secret-first-agent.html)** - run a useful support agent with a mock model before setting up a provider key.
|
||||
6. **[Your First Agent](guides/your-first-agent.html)** - turn this service into an agent-callable tool, chat with it, and learn the `micro agent preflight` → `micro run` → `micro chat` loop.
|
||||
7. **[Debugging your agent](guides/debugging-agents.html)** - inspect service registration, tool calls, run history, memory, provider failures, and flow handoffs when the agent does something surprising.
|
||||
8. **[0→hero Reference](guides/zero-to-hero.html)** - walk the maintained scaffold → run → chat → inspect → deploy dry-run path that proves services, agents, and workflows together.
|
||||
1. **[Smallest first-agent example](https://github.com/micro/go-micro/tree/master/examples/first-agent)** - run a mock-model, no-secret agent before adding provider keys.
|
||||
2. **[Your First Agent](guides/your-first-agent.html)** - turn this service into an agent-callable tool, chat with it, and learn the `micro agent preflight` → `micro run` → `micro chat` loop.
|
||||
3. **[Debugging your agent](guides/debugging-agents.html)** - inspect service registration, tool calls, run history, memory, provider failures, and flow handoffs when the agent does something surprising.
|
||||
4. **[0→hero Reference](guides/zero-to-hero.html)** - walk the maintained scaffold → run → chat → inspect → deploy dry-run path that proves services, agents, and workflows together.
|
||||
|
||||
After that first-agent path, branch out to:
|
||||
|
||||
@@ -119,3 +113,4 @@ publisher.Publish(ctx, &UserCreatedEvent{
|
||||
- **[Discord Community](https://discord.gg/G8Gk5j3uXr)** - Chat with other users
|
||||
- **[GitHub Issues](https://github.com/micro/go-micro/issues)** - Report bugs or request features
|
||||
- **[Documentation](https://go-micro.dev/docs/)** - Complete docs
|
||||
|
||||
|
||||
Reference in New Issue
Block a user