chore: import upstream snapshot with attribution

examples/first-agent/README.md

@@ -0,0 +1,55 @@
+# First Agent
+
+This is the smallest runnable service-backed agent in the repository. It sits
+between `micro new helloworld` and the full [`examples/support`](../support/)
+0→hero reference.
+
+It runs with a deterministic mock model, so you do not need `ANTHROPIC_API_KEY`,
+`OPENAI_API_KEY`, or any other provider secret.
+
+```bash
+go run ./examples/first-agent
+```
+
+Expected transcript:
+
+```text
+First agent (provider: mock, no API key)
+> Summarize my next steps
+  [notes] listed starter notes
+assistant: Your first agent read the notes service and found three steps: install the CLI, run a service, then chat with an agent.
+✓ service-backed agent completed without provider secrets
+```
+
+## What it demonstrates
+
+- `notes` is a normal Go Micro service with one RPC method.
+- `assistant` is an agent scoped to that service via `agent.Services("notes")`.
+- The mock model requests the service tool through the normal agent tool handler.
+- The final answer proves the service → agent path without a live model key.
+
+CI keeps this path runnable with:
+
+```bash
+go test ./examples/first-agent
+```
+
+## Next chat, inspect, and debug breadcrumbs
+
+This example exits after one in-process `assistant.Ask` call so it stays tiny and
+provider-free. When you move from this transcript to a long-running agent, keep
+these commands nearby:
+
+```bash
+micro run
+micro chat assistant --prompt "Summarize my next steps"
+micro inspect agent assistant
+micro agent doctor assistant
+```
+
+Use the [no-secret first-agent guide](../../internal/website/docs/guides/no-secret-first-agent.md)
+to compare this transcript with the CLI demo, then keep the
+[debugging guide](../../internal/website/docs/guides/debugging-agents.md) open for
+preflight, doctor, inspect, and history checks. After that, continue to
+[`examples/support`](../support/) for the full services → agents → workflows
+lifecycle with a flow trigger and an approval gate.

examples/first-agent/main.go

@@ -0,0 +1,161 @@
+// First Agent — the smallest runnable service-backed agent.
+//
+// Run:
+//
+//	go run ./examples/first-agent
+//
+// It uses a deterministic mock model, so it needs no provider API key. The
+// point is to show the first agent shape: a service exposes a tool, an agent
+// discovers that service, the model asks to call the tool, and the agent returns
+// a final answer.
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"time"
+
+	"go-micro.dev/v6/agent"
+	"go-micro.dev/v6/ai"
+	"go-micro.dev/v6/broker"
+	"go-micro.dev/v6/client"
+	"go-micro.dev/v6/registry"
+	"go-micro.dev/v6/selector"
+	"go-micro.dev/v6/service"
+	"go-micro.dev/v6/store"
+)
+
+type ListNotesRequest struct{}
+
+type ListNotesResponse struct {
+	Notes []string `json:"notes" description:"Notes the assistant can summarize"`
+}
+
+type NotesService struct{ w io.Writer }
+
+// List returns the starter notes the first agent can read.
+// @example {}
+func (s *NotesService) List(ctx context.Context, req *ListNotesRequest, rsp *ListNotesResponse) error {
+	rsp.Notes = []string{"Install the micro CLI", "Run a service", "Chat with an agent"}
+	fmt.Fprintln(s.w, "  [notes] listed starter notes")
+	return nil
+}
+
+type mockModel struct{ opts ai.Options }
+
+func newMock(opts ...ai.Option) ai.Model {
+	m := &mockModel{}
+	_ = m.Init(opts...)
+	return m
+}
+
+func (m *mockModel) Init(opts ...ai.Option) error {
+	for _, o := range opts {
+		o(&m.opts)
+	}
+	return nil
+}
+func (m *mockModel) Options() ai.Options { return m.opts }
+func (m *mockModel) String() string      { return "first-agent-mock" }
+func (m *mockModel) Stream(context.Context, *ai.Request, ...ai.GenerateOption) (ai.Stream, error) {
+	return nil, fmt.Errorf("stream not supported by first-agent mock")
+}
+
+func (m *mockModel) Generate(ctx context.Context, req *ai.Request, _ ...ai.GenerateOption) (*ai.Response, error) {
+	for _, tool := range req.Tools {
+		if strings.Contains(tool.Name, "List") && m.opts.ToolHandler != nil {
+			m.opts.ToolHandler(ctx, ai.ToolCall{ID: "list-notes", Name: tool.Name, Input: map[string]any{}})
+			break
+		}
+	}
+	return &ai.Response{Answer: "Your first agent read the notes service and found three steps: install the CLI, run a service, then chat with an agent."}, nil
+}
+
+func waitFor(reg registry.Registry, names ...string) error {
+	deadline := time.Now().Add(5 * time.Second)
+	for _, name := range names {
+		for {
+			if svcs, err := reg.GetService(name); err == nil && len(svcs) > 0 && len(svcs[0].Nodes) > 0 {
+				break
+			}
+			if time.Now().After(deadline) {
+				return fmt.Errorf("timed out waiting for %s", name)
+			}
+			time.Sleep(20 * time.Millisecond)
+		}
+	}
+	return nil
+}
+
+func runFirstAgent() error {
+	return runFirstAgentWithWriter(os.Stdout)
+}
+
+func runFirstAgentWithWriter(w io.Writer) error {
+	ai.Register("first-agent-mock", newMock)
+
+	reg := registry.NewMemoryRegistry()
+	br := broker.NewMemoryBroker()
+	if err := br.Init(); err != nil {
+		return fmt.Errorf("init broker: %w", err)
+	}
+	if err := br.Connect(); err != nil {
+		return fmt.Errorf("connect broker: %w", err)
+	}
+	defer br.Disconnect()
+	cl := client.NewClient(client.Registry(reg), client.Selector(selector.NewSelector(selector.Registry(reg))), client.Broker(br))
+
+	notes := service.New(service.Name("notes"), service.Address("127.0.0.1:0"), service.Registry(reg), service.Client(cl), service.Broker(br), service.HandleSignal(false))
+	if err := notes.Handle(&NotesService{w: w}); err != nil {
+		return fmt.Errorf("handle notes: %w", err)
+	}
+	svcErr := make(chan error, 1)
+	go func() { svcErr <- notes.Run() }()
+	defer notes.Server().Stop()
+
+	assistant := agent.New(
+		agent.Name("assistant"),
+		agent.Address("127.0.0.1:0"),
+		agent.Services("notes"),
+		agent.Prompt("You are a friendly first agent. Use the notes service before answering."),
+		agent.Provider("first-agent-mock"),
+		agent.WithRegistry(reg),
+		agent.WithClient(cl),
+		agent.WithBroker(br),
+		agent.WithStore(store.NewMemoryStore()),
+	)
+	agentErr := make(chan error, 1)
+	go func() { agentErr <- assistant.Run() }()
+	defer assistant.Stop()
+
+	if err := waitFor(reg, "notes", "assistant"); err != nil {
+		select {
+		case runErr := <-svcErr:
+			return fmt.Errorf("run notes: %w", runErr)
+		case runErr := <-agentErr:
+			return fmt.Errorf("run assistant: %w", runErr)
+		default:
+		}
+		return err
+	}
+
+	fmt.Fprintln(w, "First agent (provider: mock, no API key)")
+	fmt.Fprintln(w, "> Summarize my next steps")
+	resp, err := assistant.Ask(context.Background(), "Summarize my next steps")
+	if err != nil {
+		return fmt.Errorf("ask assistant: %w", err)
+	}
+	fmt.Fprintln(w, "assistant:", resp.Reply)
+	fmt.Fprintln(w, "✓ service-backed agent completed without provider secrets")
+	return nil
+}
+
+func main() {
+	if err := runFirstAgent(); err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+}

examples/first-agent/main_test.go

@@ -0,0 +1,71 @@
+package main
+
+import (
+	"bytes"
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestRunFirstAgent(t *testing.T) {
+	var out bytes.Buffer
+	if err := runFirstAgentWithWriter(&out); err != nil {
+		t.Fatalf("first-agent example failed: %v", err)
+	}
+
+	want := strings.TrimSpace(readExpectedTranscript(t))
+	got := strings.TrimSpace(out.String())
+	if got != want {
+		t.Fatalf("first-agent transcript drifted from README.md\n--- got ---\n%s\n--- want ---\n%s", got, want)
+	}
+}
+
+func TestReadmeDocumentsNextBreadcrumbs(t *testing.T) {
+	b, err := os.ReadFile("README.md")
+	if err != nil {
+		t.Fatalf("read README.md: %v", err)
+	}
+	readme := string(b)
+	start := strings.Index(readme, "## Next chat, inspect, and debug breadcrumbs")
+	if start < 0 {
+		t.Fatal("README.md missing next chat, inspect, and debug breadcrumbs section")
+	}
+	section := readme[start:]
+	for _, want := range []string{
+		"micro run",
+		"micro chat assistant --prompt \"Summarize my next steps\"",
+		"micro inspect agent assistant",
+		"micro agent doctor assistant",
+		"no-secret-first-agent.md",
+		"debugging-agents.md",
+		"examples/support",
+	} {
+		if !strings.Contains(section, want) {
+			t.Fatalf("README.md next breadcrumbs missing %q", want)
+		}
+	}
+}
+
+func readExpectedTranscript(t *testing.T) string {
+	t.Helper()
+	b, err := os.ReadFile("README.md")
+	if err != nil {
+		t.Fatalf("read README.md: %v", err)
+	}
+	readme := string(b)
+	const fence = "```text"
+	start := strings.Index(readme, "Expected transcript:")
+	if start < 0 {
+		t.Fatal("README.md missing Expected transcript section")
+	}
+	fenceStart := strings.Index(readme[start:], fence)
+	if fenceStart < 0 {
+		t.Fatal("README.md missing transcript text fence")
+	}
+	start += fenceStart + len(fence)
+	end := strings.Index(readme[start:], "```")
+	if end < 0 {
+		t.Fatal("README.md missing closing transcript fence")
+	}
+	return readme[start : start+end]
+}