Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions .github/workflows/universe.yml → .github/workflows/harness.yml
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
name: Universe (E2E)
name: Harness (E2E)

# Spins up a mini go-micro world end-to-end — services, a durable flow
# that crashes and resumes, and an agent — then shuts it down. Everything
# is real except the LLM, which is mocked, so the default job is
# deterministic and needs no secrets. A second job runs the same scenario
# against a live model when an API key secret is configured.
# Runs the end-to-end harnesses for agents, services, flows, and provider
# conformance. The default job uses deterministic mock LLMs and needs no
# secrets. A second job runs the same harnesses against any live providers
# whose API key secrets are configured.

on:
push:
Expand All @@ -16,8 +15,8 @@ on:
workflow_dispatch:

jobs:
universe:
name: Mini universe (mock LLM)
harness:
name: Harnesses (mock LLM)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
Expand All @@ -34,12 +33,12 @@ jobs:
- name: Plan-delegate harness
run: go run ./internal/harness/plan-delegate

universe-live:
name: Mini universe (live LLM, if key present)
harness-live:
name: Provider harnesses (live LLM, if keys present)
runs-on: ubuntu-latest
# Only on the daily schedule or a manual run — never automatically on
# every push/PR, so changes don't quietly burn API credits. Trigger it
# by hand (Actions → Universe → Run workflow) when changing the agent,
# by hand (Actions → Harness → Run workflow) when changing the agent,
# flow, or AI internals and you want a real-model check.
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
steps:
Expand All @@ -48,12 +47,13 @@ jobs:
with:
go-version: stable
cache: true
- name: Universe against a live model (AtlasCloud)
- name: Provider conformance against configured live models
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
TOGETHER_API_KEY: ${{ secrets.TOGETHER_API_KEY }}
ATLASCLOUD_API_KEY: ${{ secrets.ATLASCLOUD_API_KEY }}
run: |
if [ -z "$ATLASCLOUD_API_KEY" ]; then
echo "No ATLASCLOUD_API_KEY secret configured — skipping the live run."
exit 0
fi
go run ./internal/harness/universe -provider atlascloud
run: go run ./internal/harness/provider-conformance
9 changes: 8 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ LDFLAGS = -X $(GIT_IMPORT).BuildDate=$(BUILD_DATE) -X $(GIT_IMPORT).GitCommit=$(
# GORELEASER_DOCKER_IMAGE = ghcr.io/goreleaser/goreleaser-cross:v1.25.7
GORELEASER_DOCKER_IMAGE = ghcr.io/goreleaser/goreleaser:latest

.PHONY: test test-race test-coverage harness lint fmt install-tools proto clean help gorelease-dry-run gorelease-dry-run-docker
.PHONY: test test-race test-coverage harness provider-conformance lint fmt install-tools proto clean help gorelease-dry-run gorelease-dry-run-docker

# Default target
help:
Expand All @@ -18,6 +18,8 @@ help:
@echo " make test-race - Run tests with race detector"
@echo " make test-coverage - Run tests with coverage"
@echo " make lint - Run linter"
@echo " make harness - Run deterministic end-to-end harnesses"
@echo " make provider-conformance - Run harnesses against configured live providers"
@echo " make fmt - Format code"
@echo " make install-tools - Install development tools"
@echo " make proto - Generate protobuf code"
Expand Down Expand Up @@ -47,6 +49,11 @@ harness:
go run ./internal/harness/agent-flow
go run ./internal/harness/plan-delegate

# Run the same harnesses against every configured live provider. Providers
# without API keys are skipped; configured providers must pass.
provider-conformance:
go run ./internal/harness/provider-conformance

# Run linter
lint:
golangci-lint run
Expand Down
21 changes: 18 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Go Micro [![Go.Dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/go-micro.dev/v6?tab=doc) [![Go Report Card](https://goreportcard.com/badge/github.com/go-micro/go-micro)](https://goreportcard.com/report/github.com/go-micro/go-micro)

Go Micro is a framework for building agents and services in Go.
Go Micro is an **agent harness** and service framework for Go.

Build an agent and it gets a model, memory, and tools, manages your services, and is reachable over [MCP](https://modelcontextprotocol.io/) and [A2A](https://a2a-protocol.org). Write services and they register, discover each other, and every endpoint is automatically an AI-callable tool. Orchestrate the deterministic parts with flows. Agents, services, and flows are all Go code — the same primitives, the same deployment — because an agent is a distributed system, and building one is building a service.
A harness is the runtime around an agent: the tools it can call, the memory it keeps, the guardrails that bound it, the workflows that trigger it, the services it depends on, and the protocols other agents use to reach it. Go Micro gives you that harness as Go code. Build an agent and it gets a model, memory, tools, planning, delegation, guardrails, and service discovery; it is reachable over [MCP](https://modelcontextprotocol.io/) and [A2A](https://a2a-protocol.org). Write services and every endpoint becomes an AI-callable tool. Orchestrate the deterministic parts with durable flows. Agents, services, and flows share one runtime because an agent is a distributed system, and building one is building a service.

## Sponsors

Expand All @@ -21,6 +21,7 @@ Running Go Micro in production, or building on it and want help? Paid **support,
## Contents

- [Quick Start](#quick-start)
- [Why an Agent Harness](#why-an-agent-harness)
- [Writing Services](#writing-services)
- [Building Agents](#building-agents) — [Plan & Delegate](#plan--delegate), [Pluggable](#batteries-included-pluggable), [Paid tools (x402)](#paid-tools-x402), [A2A](#reachable-by-other-agents-a2a)
- [Features](#features)
Expand Down Expand Up @@ -116,6 +117,20 @@ When you need a capability that doesn't exist, the agent generates a new service

Edit the generated code by hand at any time — re-running preserves your changes. [Read more](https://go-micro.dev/blog/13).

## Why an Agent Harness

The first wave of agent frameworks helped developers put a model in a loop. The next problem is operating that loop: connecting it to real tools, scoping what it can touch, preserving state, routing work to specialists, recovering from failures, observing what happened, and letting other agents call it. That is harness work.

Go Micro's answer is to make the harness the same thing you already deploy:

- **Tools are services** — endpoint metadata becomes tool schema; RPC executes the call.
- **Agents are services** — they register, discover, load-balance, and expose `Agent.Chat`.
- **Workflows are durable code paths** — use flows when the path is known; dispatch to agents when it is not.
- **Safety lives at execution** — `MaxSteps`, `LoopLimit`, `ApproveTool`, and tool wrappers run where actions happen.
- **Interop is built in** — MCP for tools, A2A for agents, x402 for paid tools.

Use Go Micro when the agent has to operate a system, not just answer a prompt.

## Writing Services

Under the hood, a service is a struct with methods. Doc comments and `@example` tags become tool descriptions for AI agents automatically.
Expand Down Expand Up @@ -200,7 +215,7 @@ micro call task-mgr Agent.Chat '{"message": "What tasks are overdue?"}'

### Plan & Delegate

Every agent gets two built-in capabilities, exposed as tools — no extra setup, no harness:
Every agent gets two built-in harness capabilities, exposed as tools — no extra setup or separate graph runtime:

- **`plan`** — for multi-step work, the agent records an ordered plan in its store-backed memory and stays oriented across turns.
- **`delegate`** — the agent hands a self-contained subtask to another agent. If a registered agent already owns the relevant services, the hand-off goes over RPC to that agent; otherwise a focused, short-lived sub-agent is created for the subtask with its own isolated context.
Expand Down
68 changes: 68 additions & 0 deletions cmd/micro/cli/new/contract_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
package new

import (
"flag"
"os"
"os/exec"
"path/filepath"
"strings"
"testing"

"github.com/urfave/cli/v2"
)

// TestZeroToOneContract locks the documented getting-started path:
// `micro new helloworld` must produce an ordinary Go service that can be
// tested by the Go toolchain. The generated module is pointed back at this
// checkout so the contract stays local and deterministic in CI.
func TestZeroToOneContract(t *testing.T) {
repoRoot, err := filepath.Abs(filepath.Join("..", "..", "..", ".."))
if err != nil {
t.Fatal(err)
}

tmp := t.TempDir()
oldwd, err := os.Getwd()
if err != nil {
t.Fatal(err)
}
if err := os.Chdir(tmp); err != nil {
t.Fatal(err)
}
defer os.Chdir(oldwd)

set := flag.NewFlagSet("micro-new", flag.ContinueOnError)
if err := set.Parse([]string{"helloworld"}); err != nil {
t.Fatal(err)
}
ctx := cli.NewContext(cli.NewApp(), set, nil)

if err := Run(ctx); err != nil {
t.Fatalf("micro new helloworld: %v", err)
}

serviceDir := filepath.Join(tmp, "helloworld")
for _, rel := range []string{"go.mod", "main.go", "handler/helloworld.go", "README.md", "Makefile"} {
if _, err := os.Stat(filepath.Join(serviceDir, rel)); err != nil {
t.Fatalf("generated file %s: %v", rel, err)
}
}

modPath := filepath.Join(serviceDir, "go.mod")
mod, err := os.ReadFile(modPath)
if err != nil {
t.Fatal(err)
}
modText := strings.Replace(string(mod), "go-micro.dev/v6 latest", "go-micro.dev/v6 v6.0.0", 1)
modText += "\nreplace go-micro.dev/v6 => " + filepath.ToSlash(repoRoot) + "\n"
if err := os.WriteFile(modPath, []byte(modText), 0644); err != nil {
t.Fatal(err)
}

cmd := exec.Command("go", "test", "./...")
cmd.Dir = serviceDir
out, err := cmd.CombinedOutput()
if err != nil {
t.Fatalf("generated service go test ./... failed: %v\n%s", err, out)
}
}
Loading
Loading