Enforce blocking golangci-lint in CI and clear lint backlog (#2996)

* lint: clear the golangci-lint backlog and enforce a blocking lint in CI

Fixes #2988. Brings 'golangci-lint run ./...' to zero issues (was ~373):

- errcheck: explicitly ignore fire-and-forget calls with '_ =' (and a small
  errcheck.exclude-functions list for response writes — json Encoder.Encode,
  http ResponseWriter.Write, fmt.Fprint*); genuine cases handled.
- unused: remove dead code (unexported decls and dead test helpers) and the
  imports they orphaned.
- staticcheck: ST1005 error strings, ST1016 receiver names, S1000/S1017/S1019/
  S1023 simplifications, SA4004/SA4006/SA4010 dead code, SA1021 net.IP.Equal,
  SA6002 (store *[]byte in sync.Pool).
- govet: fix a context leak (lostcancel) in internal/util/mdns and move
  t.Fatal/Fatalf out of goroutines (testinggoroutine) in tests.
- ineffassign, unconvert: mechanical fixes.

CI: the Lint workflow now runs a blocking full-tree 'golangci-lint run' on
pushes and PRs (dropped only-new-issues now that the tree is clean).

Verified: go build, go vet, test compilation, and unit tests for the
behaviourally-touched packages all pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CmdEY7pYmV5zzwCjNJ4ykL

* website: emit go-source meta for /vN paths

pkg.go.dev uses go-source to link to the right files and lines. The /vN
go-get response now returns go-source alongside go-import. Does not affect
go install resolution.

---------

Co-authored-by: Claude <noreply@anthropic.com>

.github/FUNDING.yml

@@ -1 +1,2 @@
 github: asim
+custom: ["https://go-micro.dev/docs/support.html"]

.github/ISSUE_TEMPLATE/bug_report.md

@@ -48,4 +48,4 @@ Add any other context about the problem here.
 - [Troubleshooting Guide](https://github.com/micro/go-micro/tree/master/internal/website/docs/getting-started.md)
 - [Examples](https://github.com/micro/go-micro/tree/master/examples)
 - [API Reference](https://pkg.go.dev/go-micro.dev/v5)
-- [Discord Community](https://discord.gg/jwTYuUVAGh)
+- [Discord Community](https://discord.gg/WeMU5AGxD)

.github/ISSUE_TEMPLATE/commercial_support.md

@@ -0,0 +1,23 @@
+---
+name: Commercial Support / Consulting
+about: Inquire about paid support, consulting, training, or a retainer
+title: '[SUPPORT] '
+labels: commercial-support
+assignees: asim
+---
+
+## What are you building?
+A short description of your project and how you're using (or planning to use) Go Micro.
+
+## What do you need?
+- [ ] Production support / retainer (priority fixes, direct line, response SLA)
+- [ ] Consulting (integration, architecture, agent design)
+- [ ] Training / onboarding for a team
+- [ ] Sponsored feature or fix
+- [ ] Not sure yet — let's talk
+
+## Scale & timeline
+Team size, where you're running it, and any timeline that matters.
+
+## Anything else?
+Links, context, constraints. For anything you'd rather keep private, become a [sponsor](https://github.com/sponsors/asim) and message directly.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 💖 Sponsor Go Micro
+    url: https://github.com/sponsors/asim
+    about: Fund ongoing development and see your name or logo on the project.
+  - name: 📖 Documentation
+    url: https://go-micro.dev/docs
+    about: Guides, examples, and the full reference.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -39,4 +39,4 @@ Add any other context, code examples, or screenshots about the feature request h
 - [Roadmap](https://github.com/micro/go-micro/blob/master/ROADMAP.md)
 - [Contributing Guide](https://github.com/micro/go-micro/blob/master/CONTRIBUTING.md)
 - [Architecture Docs](https://github.com/micro/go-micro/tree/master/internal/website/docs/architecture.md)
-- [Discord Community](https://discord.gg/jwTYuUVAGh)
+- [Discord Community](https://discord.gg/WeMU5AGxD)

.github/workflows/lint.yaml

@@ -0,0 +1,30 @@
+name: Lint
+on:
+  push:
+    branches:
+      - "**"
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+    branches:
+      - "**"
+jobs:
+  golangci:
+    name: golangci-lint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: 1.24
+          check-latest: true
+          cache: true
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v8
+        with:
+          version: v2.5.0

.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: goreleaser
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+  id-token: write
+  packages: write
+  attestations: write
+jobs:
+  goreleaser:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      -
+        name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: stable
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      -
+        name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+      -
+        name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      -
+        name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v7
+        with:
+          distribution: goreleaser
+          version: '~> v2'
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/universe.yml

@@ -0,0 +1,59 @@
+name: Universe (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.
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+  schedule:
+    - cron: "17 6 * * *" # daily, so the world is exercised even without changes
+  workflow_dispatch:
+
+jobs:
+  universe:
+    name: Mini universe (mock LLM)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: stable
+          cache: true
+      - name: Build
+        run: go build ./...
+      - name: Universe end-to-end (asserts; exits non-zero on failure)
+        run: go run ./internal/harness/universe
+      - name: Agent-flow harness
+        run: go run ./internal/harness/agent-flow
+      - name: Plan-delegate harness
+        run: go run ./internal/harness/plan-delegate
+
+  universe-live:
+    name: Mini universe (live LLM, if key 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,
+    # flow, or AI internals and you want a real-model check.
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: stable
+          cache: true
+      - name: Universe against a live model (AtlasCloud)
+        env:
+          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

.gitignore

@@ -57,3 +57,8 @@ examples/mcp/hello/hello
 # IDE-specific files
 .DS_Store
 /micro
+
+# Built example/harness binaries (go build ./path/... drops these at repo root)
+/plan-delegate
+/agent-plan-delegate
+/micro-mcp-gateway

.golangci.yaml

@@ -1,251 +1,63 @@
-# This file contains all available configuration options
-# with their default values.
+version: "2"
 
-# options for analysis running
 run:
-  # go: '1.18'
-  # default concurrency is a available CPU number
-  # concurrency: 4
-
-  # timeout for analysis, e.g. 30s, 5m, default is 1m
-  deadline: 10m
-
-  # exit code when at least one issue was found, default is 1
-  issues-exit-code: 1
-
-  # include test files or not, default is true
+  timeout: 5m
   tests: true
 
-  # which files to skip: they will be analyzed, but issues from them
-  # won't be reported. Default value is empty list, but there is
-  # no need to include all autogenerated files, we confidently recognize
-  # autogenerated files. If it's not please let us know.
-  skip-files:
-    []
-    # - .*\\.pb\\.go$
-
-  allow-parallel-runners: true
-
-  # list of build tags, all linters use it. Default is empty list.
-  build-tags: []
-
-# output configuration options
-output:
-  # Format: colored-line-number|line-number|json|tab|checkstyle|code-climate|junit-xml|github-actions
-  #
-  # Multiple can be specified by separating them by comma, output can be provided
-  # for each of them by separating format name and path by colon symbol.
-  # Output path can be either `stdout`, `stderr` or path to the file to write to.
-  # Example: "checkstyle:report.json,colored-line-number"
-  #
-  # Default: colored-line-number
-  format: colored-line-number
-  # Print lines of code with issue.
-  # Default: true
-  print-issued-lines: true
-  # Print linter name in the end of issue text.
-  # Default: true
-  print-linter-name: true
-  # Make issues output unique by line.
-  # Default: true
-  uniq-by-line: true
-  # Add a prefix to the output file references.
-  # Default is no prefix.
-  path-prefix: ""
-  # Sort results by: filepath, line and column.
-  sort-results: true
-
-# all available settings of specific linters
-linters-settings:
-  wsl:
-    allow-cuddle-with-calls: ["Lock", "RLock", "defer"]
-  funlen:
-    lines: 80
-    statements: 60
-  varnamelen:
-    # The longest distance, in source lines, that is being considered a "small scope".
-    # Variables used in at most this many lines will be ignored.
-    # Default: 5
-    max-distance: 26
-    ignore-names:
-      - err
-      - id
-      - ch
-      - wg
-      - mu
-    ignore-decls:
-      - c echo.Context
-      - t testing.T
-      - f *foo.Bar
-      - e error
-      - i int
-      - const C
-      - T any
-      - m map[string]int
-  errcheck:
-    # report about not checking of errors in type assetions: `a := b.(MyStruct)`;
-    # default is false: such cases aren't reported by default.
-    check-type-assertions: true
-
-    # report about assignment of errors to blank identifier: `num, _ := strconv.Atoi(numStr)`;
-    # default is false: such cases aren't reported by default.
-    check-blank: true
-  govet:
-    # report about shadowed variables
-    check-shadowing: false
-  gofmt:
-    # simplify code: gofmt with `-s` option, true by default
-    simplify: true
-  gocyclo:
-    # minimal code complexity to report, 30 by default (but we recommend 10-20)
-    min-complexity: 15
-  maligned:
-    # print struct with more effective memory layout or not, false by default
-    suggest-new: true
-  dupl:
-    # tokens count to trigger issue, 150 by default
-    threshold: 100
-  goconst:
-    # minimal length of string constant, 3 by default
-    min-len: 3
-    # minimal occurrences count to trigger, 3 by default
-    min-occurrences: 3
-  depguard:
-    list-type: blacklist
-    # Packages listed here will reported as error if imported
-    packages:
-      - github.com/golang/protobuf/proto
-  misspell:
-    # Correct spellings using locale preferences for US or UK.
-    # Default is to use a neutral variety of English.
-    # Setting locale to US will correct the British spelling of 'colour' to 'color'.
-    locale: US
-  lll:
-    # max line length, lines longer will be reported. Default is 120.
-    # '\t' is counted as 1 character by default, and can be changed with the tab-width option
-    line-length: 120
-    # tab width in spaces. Default to 1.
-    tab-width: 1
-  unused:
-    # treat code as a program (not a library) and report unused exported identifiers; default is false.
-    # XXX: if you enable this setting, unused will report a lot of false-positives in text editors:
-    # if it's called for subdir of a project it can't find funcs usages. All text editor integrations
-    # with golangci-lint call it on a directory with the changed file.
-    check-exported: false
-  unparam:
-    # call graph construction algorithm (cha, rta). In general, use cha for libraries,
-    # and rta for programs with main packages. Default is cha.
-    algo: cha
-
-    # Inspect exported functions, default is false. Set to true if no external program/library imports your code.
-    # XXX: if you enable this setting, unparam will report a lot of false-positives in text editors:
-    # if it's called for subdir of a project it can't find external interfaces. All text editor integrations
-    # with golangci-lint call it on a directory with the changed file.
-    check-exported: false
-  nakedret:
-    # make an issue if func has more lines of code than this setting and it has naked returns; default is 30
-    max-func-lines: 60
-  nolintlint:
-    allow-unused: false
-    allow-leading-space: false
-    allow-no-explanation: []
-    require-explanation: false
-    require-specific: true
-  prealloc:
-    # XXX: we don't recommend using this linter before doing performance profiling.
-    # For most programs usage of prealloc will be a premature optimization.
-
-    # Report preallocation suggestions only on simple loops that have no returns/breaks/continues/gotos in them.
-    # True by default.
-    simple: true
-    range-loops: true # Report preallocation suggestions on range loops, true by default
-    for-loops: false # Report preallocation suggestions on for loops, false by default
-  cyclop:
-    # the maximal code complexity to report
-    max-complexity: 20
-  gomoddirectives:
-    replace-local: true
-    retract-allow-no-explanation: false
-    exclude-forbidden: true
-
 linters:
-  enable-all: true
-  disable-all: false
-  fast: false
-  disable:
-    - golint
-    - varcheck
-    - ifshort
-    - structcheck
-    - deadcode
-    # - nosnakecase
-    - interfacer
-    - maligned
-    - scopelint
-    - exhaustivestruct
-    - testpackage
-    - promlinter
-    - nonamedreturns
-    - makezero
-    - gofumpt
-    - nlreturn
-    - thelper
+  # Start from the standard set (errcheck, govet, ineffassign, staticcheck,
+  # unused) and add a few low-noise, high-value linters on top.
+  default: standard
+  enable:
+    - bodyclose
+    - misspell
+    - unconvert
+    - usestdlibvars
+  settings:
+    errcheck:
+      exclude-functions:
+        - (*encoding/json.Encoder).Encode
+        - (net/http.ResponseWriter).Write
+        - fmt.Fprintf
+        - fmt.Fprint
+        - fmt.Fprintln
+    misspell:
+      locale: US
+    staticcheck:
+      checks:
+        - all
+        # Deprecations are tracked separately; some (e.g. gRPC dial options)
+        # are kept intentionally for compatibility. Migrate them on their own.
+        - -SA1019
+        # Initialism/naming convention (Id->ID, Http->HTTP, ...). The remaining
+        # offenders are exported identifiers (e.g. web.Id, web.DefaultId) whose
+        # rename is a breaking API change; not worth it in a lint-bootstrap pass.
+        - -ST1003
+  exclusions:
+    # Use golangci-lint's built-in sensible exclusions and skip generated code.
+    generated: lax
+    presets:
+      - comments
+      - common-false-positives
+      - legacy
+      - std-error-handling
+    rules:
+      # The protobuf code generator is a port of upstream protoc-gen-go and
+      # keeps its structure; don't flag its unused legacy helpers.
+      - path: cmd/protoc-gen-micro/generator/
+        linters:
+          - unused
+      # Tests are held to a looser standard.
+      - path: _test\.go
+        linters:
+          - bodyclose
+          - errcheck
+      # Demo/harness code: fire-and-forget calls are fine and `_ =` noise hurts
+      # readability of examples.
+      - path: (^|/)(examples|internal/harness)/
+        linters:
+          - errcheck
 
-    # Can be considered to be enabled
-    - gochecknoinits
-    - gochecknoglobals # RIP
-    - dogsled
-    - wrapcheck
-    - paralleltest
-    - ireturn
-    - gomnd
-    - goerr113
-    - exhaustruct
-    - containedctx
-    - godox
-    - forcetypeassert
-    - gci
-    - lll
-
-issues:
-  # List of regexps of issue texts to exclude, empty list by default.
-  # But independently from this option we use default exclude patterns,
-  # it can be disabled by `exclude-use-default: false`. To list all
-  # excluded by default patterns execute `golangci-lint run --help`
-  # exclude:
-  #   - package comment should be of the form "Package services ..." # revive
-  #   - ^ST1000 # ST1000: at least one file in a package should have a package comment (stylecheck)
-
-  # exclude-rules:
-  #   - path: internal/app/machined/pkg/system/services
-  #     linters:
-  #       - dupl
-  exclude-rules:
-    - path: _test\.go
-      linters:
-        - gocyclo
-        - dupl
-        - gosec
-        - funlen
-        - varnamelen
-        - wsl
-
-  # Independently from option `exclude` we use default exclude patterns,
-  # it can be disabled by this option. To list all
-  # excluded by default patterns execute `golangci-lint run --help`.
-  # Default value for this option is true.
-  exclude-use-default: false
-
-  # Maximum issues count per one linter. Set to 0 to disable. Default is 50.
-  max-issues-per-linter: 0
-
-  # Maximum count of issues with the same text. Set to 0 to disable. Default is 3.
-  max-same-issues: 0
-
-  # Show only new issues: if there are unstaged changes or untracked files,
-  # only those changes are analyzed, else only changes in HEAD~ are analyzed.
-  # It's a super-useful option for integration of golangci-lint into existing
-  # large codebase. It's not practical to fix all existing issues at the moment
-  # of integration: much better don't allow issues in new code.
-  # Default is false.
-  new: false
+formatters:
+  enable:
+    - gofmt

.goreleaser.yaml

@@ -0,0 +1,136 @@
+# yaml-language-server: $schema=https://goreleaser.com/static/schema.json
+# vim: set ts=2 sw=2 tw=0 fo=cnqoj
+
+version: 2
+
+before:
+  hooks:
+    - go mod tidy
+
+builds:
+  - main: ./cmd/micro
+    id: micro
+    binary: micro
+    env:
+      - CGO_ENABLED=0
+      - >-
+        {{- if eq .Os "darwin" }}
+          {{- if eq .Arch "amd64"}}CC=o64-clang{{- end }}
+          {{- if eq .Arch "arm64"}}CC=aarch64-apple-darwin20.2-clang{{- end }}
+        {{- end }}
+        {{- if eq .Os "windows" }}
+          {{- if eq .Arch "amd64" }}CC=x86_64-w64-mingw32-gcc{{- end }}
+        {{- end }}
+    goos:
+      - linux
+      - windows
+      - darwin
+    goarch:
+      - amd64
+      - arm
+      - arm64
+    goarm:
+      - 7
+    ignore:
+      - goos: windows
+        goarch: arm
+
+  - main: ./cmd/protoc-gen-micro
+    id: protoc-gen-micro
+    binary: protoc-gen-micro
+    env:
+      - CGO_ENABLED=0
+      - >-
+        {{- if eq .Os "darwin" }}
+          {{- if eq .Arch "amd64"}}CC=o64-clang{{- end }}
+          {{- if eq .Arch "arm64"}}CC=aarch64-apple-darwin20.2-clang{{- end }}
+        {{- end }}
+        {{- if eq .Os "windows" }}
+          {{- if eq .Arch "amd64" }}CC=x86_64-w64-mingw32-gcc{{- end }}
+        {{- end }}
+    goos:
+      - linux
+      - windows
+      - darwin
+    goarch:
+      - amd64
+      - arm
+      - arm64
+    goarm:
+      - 7
+    ignore:
+      - goos: windows
+        goarch: arm
+
+archives:
+  - id: micro
+    ids:
+      - micro
+    formats: [tar.gz]
+    name_template: >-
+      {{ .Binary }}_
+      {{- .Os }}_
+      {{- .Arch }}
+      {{- if .Arm }}v{{ .Arm }}{{ end }}
+    files:
+      - none*
+    format_overrides:
+      - goos: windows
+        formats: [zip]
+
+  - id: protoc-gen-micro
+    ids:
+      - protoc-gen-micro
+    formats: [tar.gz]
+    name_template: >-
+      {{ .Binary }}_
+      {{- .Os }}_
+      {{- .Arch }}
+      {{- if .Arm }}v{{ .Arm }}{{ end }}
+    files:
+      - none*
+    format_overrides:
+      - goos: windows
+        formats: [zip]
+
+report_sizes: true
+
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - "^docs:"
+      - "^test:"
+
+dockers_v2:
+  -
+    ids:
+      - micro
+      - protoc-gen-micro
+    images:
+      - "micro/micro"
+      - "ghcr.io/micro/go-micro"
+    tags:
+      - "v{{ .Version }}"
+      - "{{ if .IsNightly }}nightly{{ end }}"
+      - "{{ if not .IsNightly }}latest{{ end }}"
+    labels:
+      "io.artifacthub.package.readme-url": "https://raw.githubusercontent.com/micro/go-micro/refs/heads/master/README.md"
+      "io.artifacthub.package.logo-url": "https://www.gravatar.com/avatar/09d1da3ea9ee61753219a19016d6a672?s=120&r=g&d=404"
+      "org.opencontainers.image.description": "A Go Platform built for Developers"
+      "org.opencontainers.image.created": "{{.Date}}"
+      "org.opencontainers.image.title": "{{.ProjectName}}"
+      "org.opencontainers.image.revision": "{{.FullCommit}}"
+      "org.opencontainers.image.version": "{{.Version}}"
+      "org.opencontainers.image.source": "{{.GitURL}}"
+      "org.opencontainers.image.url": "{{.GitURL}}"
+      "org.opencontainers.image.licenses": "MIT"
+
+    platforms:
+      - linux/amd64
+      - linux/arm64
+
+    retry:
+      attempts: 5
+      delay: 5s
+      max_delay: 2m

CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+All notable changes to Go Micro are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/). Go Micro uses
+calendar-based versions (YYYY.MM) for the AI-native era.
+
+---
+
+## [6.0.0] - June 2026
+
+The AI-native major release. Breaking changes are listed first; everything
+else is additive. See the [v5 → v6 migration guide](internal/website/docs/guides/migration/v5-to-v6.md) — it's a small upgrade.
+
+### Changed (breaking)
+- **Module path is now `go-micro.dev/v6`.** Update imports (`go-micro.dev/v5/...` → `go-micro.dev/v6/...`) and `go install go-micro.dev/v6/cmd/micro@v6`.
+- **TLS verification is on by default.** v5 skipped verification unless `MICRO_TLS_SECURE=true`; v6 verifies by default. `MICRO_TLS_SECURE` is removed — set `MICRO_TLS_INSECURE=true` (or call `tls.InsecureConfig()`) for self-signed/dev certs.
+- **`micro.NewService(name, opts...)` is the service constructor**, symmetric with `NewAgent`/`NewFlow`. `micro.New(name, opts...)` remains as a deprecated alias; the old name-less `micro.NewService(opts...)` form is removed (pass the name positionally). Generators emit the new form.
+- **JWT auth ported in-module.** The external `github.com/micro/plugins/v5/auth/jwt` (pinned to v5) is replaced by `go-micro.dev/v6/auth/jwt/token`, now on the maintained `golang-jwt/jwt/v5`; the deprecated `dgrijalva/jwt-go` dependency is dropped.
+
+### Added
+- **A2A protocol — both directions** — `gateway/a2a` exposes registered agents over the open Agent2Agent (A2A) protocol so agents on other frameworks can discover and call them: Agent Cards are generated from registry metadata (the same way the MCP gateway derives tools), and incoming tasks are translated to the agent's existing `Agent.Chat` RPC, with no per-agent code (`micro a2a serve`). The outbound `a2a.Client` calls external A2A agents by URL, wired into `flow.A2A(url)` (a workflow step) and `delegate` to an `http(s)` URL (from inside an agent). An agent can also serve A2A **directly** without a gateway via `AgentA2A(addr)` (`a2a.NewAgentHandler`), handling tasks in-process. v1 is the synchronous JSON-RPC binding (`message/send`, `tasks/get`, card discovery); streaming and push notifications are advertised as unsupported. (`gateway/a2a/`, `cmd/micro/a2a/`)
+- **Agents (`micro.NewAgent`)** — an agent is a service with an LLM inside: it discovers its assigned services as tools, runs the model's tool loop, registers a `Chat` RPC endpoint, and is reachable like any service. `Ask` for programmatic use; `micro chat` discovers and routes to agents; `micro agent list`/`describe`. (`agent/`)
+- **Plan & delegate** — two built-in agent tools added to every agent: `plan` (an ordered, store-persisted plan surfaced back in the prompt) and `delegate` (hand a self-contained subtask to a registered agent over RPC, otherwise to an ephemeral sub-agent). No harness or graph — they're plain tools. (`agent/builtin.go`, `examples/agent-plan-delegate/`)
+- **Agent guardrails** — `MaxSteps` (stop on count), `LoopLimit` (stop repeated no-progress calls; on by default), and `ApproveTool` (human-in-the-loop / policy gate before each action), enforced at the one point every tool call passes through. (`agent/`, guide + blog)
+- **Pluggable agent memory & custom tools** — durable store-backed conversation memory by default, swappable via `AgentMemory`; register any function as a tool with `AgentTool`.
+- **Workflows (`micro.NewFlow`)** — event-driven orchestration that maps to Anthropic's workflow/agent split: an event triggers a deterministic step (or ordered durable steps), or dispatches to an agent with `FlowAgent`. (`flow/`)
+- **x402 payments** — opt-in per-call payments for tools via the x402 standard, with a pluggable facilitator and a consumer-side client + budget; the MCP gateway can advertise and require payment per tool. (`wrapper/x402/`, guide + blog)
+- **Scoped store state** — `store.Scope(s, database, table)` returns a store handle that confines every operation to a database/table without mutating the shared store (unlike `Init(Table(...))`, which is process-global and races between co-located components). Services, agents, and flows now each keep their state in their own table (`service/{name}`, `agent/{name}`, `flow/{name}`); the service path replaces the old `Init(store.Table(name))` global mutation with a scoped handle.
+- **Flow discovery & history CLI** — running flows now register in the registry as `type=flow` (and deregister on `Stop`), so they're discoverable like agents: `micro flow list` shows running flows, `micro flow runs <name>` shows a flow's durable run history from the store, and `micro agent history <name>` shows an agent's stored conversation. Live state comes from the registry; durable history from the scoped store.
+- **Durable workflows** — a flow can now be an ordered list of steps (a task with stages) that is checkpointed before and after each step, so a run survives a crash and resumes where it stopped without re-running completed steps. State carries a typed payload plus a `Stage` marker; flow-level `Retry` with a per-step override; runs retained for audit unless `DeleteOnSuccess`. Step actions: `Call` (RPC), `LLM` (model turn), `Dispatch` (to an agent), or any `StepFunc`. Durability is a pluggable `Checkpoint` (store-backed by default; implement the interface for Temporal/Restate). Runnable example: `examples/flow-durable/`. Blog: "Durable Workflows" (`internal/website/blog/24.md`).
+- **Agent tool-execution wrappers** — `AgentWrapTool` registers middleware around an agent's tool calls, the tool-side analogue of `client.CallWrapper`/`server.HandlerWrapper`. Use it for logging, metrics, retries, or policy; wrappers compose outermost-first and run outside the built-in guardrails. Includes a runnable example with observe + retry wrappers (`examples/agent-wrap-tool/`).
+- **Agent platform showcase** — full platform example (Users, Posts, Comments, Mail) mirroring [micro/blog](https://github.com/micro/blog), demonstrating how existing microservices become agent-accessible with zero code changes (`examples/mcp/platform/`).
+- **Blog post: "Your Microservices Are Already an AI Platform"** — walkthrough of agent-service interaction patterns using real-world services (`internal/website/blog/7.md`).
+- **Circuit breakers for MCP gateway** — per-tool circuit breakers protect downstream services from cascading failures. Configurable max failures, open-state timeout, and half-open probing. Available via `Options.CircuitBreaker` and `--circuit-breaker` CLI flag (`gateway/mcp/circuitbreaker.go`).
+- **Helm chart for MCP gateway** — official Helm chart at `deploy/helm/mcp-gateway/` with Deployment, Service, ServiceAccount, HPA, and Ingress templates. Supports Consul/etcd/mDNS registries, JWT auth, rate limiting, audit logging, per-tool scopes, TLS ingress, and auto-scaling.
+- **MCP gateway benchmarks** — comprehensive benchmark suite for tool listing, lookup, auth, rate limiting, and JSON serialization (`gateway/mcp/benchmark_test.go`)
+- **Workflow example** — cross-service orchestration demo with Inventory, Orders, and Notifications services showing agents chaining multi-step workflows from natural language (`examples/mcp/workflow/`)
+- **Docker Compose deployment** — production-like setup with Consul registry, standalone MCP gateway, and Jaeger tracing in one `docker-compose up` (`examples/deployment/`)
+
+---
+
+## [2026.03] - March 2026
+
+### Added
+
+#### Developer Experience
+- **`micro new` MCP templates** — `micro new myservice` generates MCP-enabled services with doc comments, `@example` tags, and `WithMCP()` wired in. Use `--no-mcp` to opt out.
+- **`micro.NewService("name")` unified API** — single way to create services: `micro.NewService("greeter")` or `micro.NewService("greeter", micro.Address(":8080"))`. Replaces `micro.NewService()` + `service.New()` dual API.
+- **`service.Handle()` simplified registration** — register handlers with `service.Handle(new(Greeter))` instead of manual `server.NewHandler` + `server.Handle`.
+- **`micro.NewGroup()` modular monoliths** — run multiple services in one binary with shared lifecycle: `micro.NewGroup(users, orders).Run()`.
+- **`mcp.WithMCP()` one-liner** — add MCP to any service with a single option: `micro.NewService("name", mcp.WithMCP(":3001"))`.
+- **CRUD example** — contact book service with 6 operations, rich agent docs, and validation patterns (`examples/mcp/crud/`).
+
+#### MCP Gateway
+- **WebSocket transport** — bidirectional JSON-RPC 2.0 streaming over WebSocket for real-time agent communication (`gateway/mcp/websocket.go`).
+- **OpenTelemetry integration** — full span instrumentation across HTTP, stdio, and WebSocket transports with W3C trace context propagation (`gateway/mcp/otel.go`).
+- **Standalone gateway binary** — `micro-mcp-gateway` with Docker support for running the MCP gateway independently of services.
+- **Per-tool auth scopes** — service-level (`server.WithEndpointScopes()`) and gateway-level (`Options.Scopes`) scope enforcement with bearer token auth.
+- **Rate limiting** — per-tool token bucket rate limiting (`Options.RateLimit`).
+- **Audit logging** — immutable audit records per tool call with trace ID, account, scopes, duration, and errors (`Options.AuditFunc`).
+
+#### AI Model Package
+- **`model.Model` interface** — unified AI provider abstraction with `Generate()` and `Stream()` methods.
+- **Anthropic Claude provider** — `model/anthropic` with tool execution and auto-calling.
+- **OpenAI GPT provider** — `model/openai` with provider auto-detection from base URL.
+
+#### Agent SDKs
+- **LangChain SDK** — `contrib/langchain-go-micro/` Python package with auto-discovery, tool generation, and multi-agent workflow examples.
+- **LlamaIndex SDK** — `contrib/go-micro-llamaindex/` Python package with RAG integration examples.
+
+#### Documentation
+- **AI-native services guide** — building services for AI agents from scratch
+- **MCP security guide** — auth, scopes, and audit logging
+- **Tool descriptions guide** — writing doc comments that improve agent performance
+- **Agent patterns guide** — architecture patterns for agent integration
+- **Error handling guide** — writing agent-friendly error responses with typed errors
+- **Troubleshooting guide** — common MCP issues and solutions
+- **Migration guide** — add MCP to existing services in 5 minutes
+
+#### CLI
+- **`micro mcp serve`** — start MCP server (stdio for Claude Code, HTTP for web agents)
+- **`micro mcp list`** — list available tools (human-readable or JSON)
+- **`micro mcp test`** — test tools with JSON input
+- **`micro mcp docs`** — generate tool documentation
+- **`micro mcp export`** — export to LangChain, OpenAPI, or JSON formats
+
+#### Agent Playground
+- **Chat-focused UI** — redesigned playground with collapsible tool calls, real-time status, and thinking indicators
+- **Provider settings** — configurable OpenAI/Anthropic provider, model, and API key
+
+### Changed
+- Service interface moved to `service.Service` with `micro.Service` as a type alias for backward compatibility.
+- `service.New()` returns `service.Service` interface (was `*ServiceImpl`).
+- `service.NewGroup()` accepts `service.Service` interface (was `*ServiceImpl`).
+- `go.mod` template in `micro new` updated to Go 1.22.
+
+### Fixed
+- Handler `Handle()` method accepts variadic `server.HandlerOption` for scopes and metadata.
+- Store initialization uses service name as table automatically.
+- Service `Stop()` properly aggregates errors from lifecycle hooks.
+
+---
+
+## [2026.02] - February 2026
+
+### Added
+- **MCP gateway library** — `gateway/mcp/` with HTTP/SSE and stdio transports, service discovery, tool generation, and JSON schema generation from Go types (2,500+ lines).
+- **CLI integration** — `micro run --mcp-address` flag to start MCP alongside services.
+- **Documentation extraction** — auto-extract tool descriptions from Go doc comments with `@example` tag and struct tag parsing.
+- **Blog post** — "Making Microservices AI-Native with MCP"
+- **MCP examples** — `examples/mcp/hello/` and `examples/mcp/documented/`
+
+---
+
+## [2026.01] - January 2026
+
+### Added
+- **`micro deploy`** — deploy services to any Linux server via SSH + systemd with `micro deploy user@server`.
+- **`micro build`** — build Go binaries and Docker images with `micro build --docker`.
+- **Blog post** — "Introducing micro deploy"
+
+---
+
+_For earlier changes, see the [git log](https://github.com/micro/go-micro/commits/master)._

CLAUDE.md

@@ -0,0 +1,146 @@
+# CLAUDE.md - Go Micro Project Guide
+
+## Project Overview
+
+Go Micro is a framework for distributed systems development in Go. It provides pluggable abstractions for service discovery, RPC, pub/sub, config, auth, storage, and more.
+
+The framework is evolving into an **AI-native platform** where every microservice is automatically accessible to AI agents via the Model Context Protocol (MCP).
+
+## Build & Test
+
+```bash
+# Run all tests
+make test
+
+# Run tests for a specific package
+go test ./gateway/mcp/...
+go test ./ai/...
+go test ./model/...
+
+# Lint
+make lint
+
+# Format
+make fmt
+
+# Build CLI
+go build -o micro ./cmd/micro
+
+# Run locally with hot reload
+micro run
+```
+
+## Project Structure
+
+```
+go-micro/
+├── agent/          # Agent abstraction (intelligent service management)
+├── ai/             # AI model providers (Anthropic, OpenAI, Gemini, etc.)
+├── auth/           # Authentication (JWT, no-op)
+├── broker/         # Message broker (NATS, RabbitMQ)
+├── cache/          # Caching (Redis)
+├── client/         # RPC client (gRPC)
+├── cmd/micro/      # CLI tool (run, deploy, mcp, build, server)
+├── codec/          # Message codecs (JSON, Proto)
+├── config/         # Dynamic config (env, file, etcd, NATS)
+├── errors/         # Error handling
+├── events/         # Event system (NATS JetStream)
+├── flow/           # Event-driven LLM orchestration
+├── gateway/
+│   ├── api/        # REST API gateway
+│   └── mcp/        # MCP gateway (core AI integration)
+│       └── deploy/ # Helm charts for MCP gateway
+├── health/         # Health checking
+├── logger/         # Logging
+├── metadata/       # Context metadata
+├── model/          # Typed data models (CRUD, queries, schemas)
+├── registry/       # Service discovery (mDNS, Consul, etcd)
+├── selector/       # Client-side load balancing
+├── server/         # RPC server
+├── service/        # Service interface + profiles
+├── store/          # Data persistence (Postgres, NATS KV)
+├── transport/      # Network transport
+├── wrapper/        # Middleware (auth, trace, metrics)
+├── examples/       # Working examples
+└── internal/       # Non-public: docs, utils, test harness
+```
+
+## Key Architectural Decisions
+
+- **Plugin architecture**: All abstractions use Go interfaces. Defaults work out of the box, everything is swappable.
+- **Progressive complexity**: Zero-config for development, full control for production.
+- **AI-native by default**: Every service is automatically an MCP tool. No extra code needed.
+- **In-repo plugins**: Plugins live in the main repo to avoid version compatibility issues.
+- **Reflection-based registration**: Handlers are registered via reflection for minimal boilerplate.
+
+## Code Conventions
+
+- Standard Go conventions (gofmt, golint)
+- Functional options pattern for configuration (`WithX()` functions)
+- Interface-first design: define the interface, then implement
+- Tests alongside code (not in separate test directories)
+- Commit messages: imperative mood, concise summary line
+
+## Current Focus & Priorities (March 2026)
+
+### Status
+- **Q1 2026 (MCP Foundation):** COMPLETE
+- **Q2 2026 (Agent DX):** COMPLETE (100%)
+- **Q3 2026 (Production):** 50% complete (ahead of schedule)
+
+### Priority 1: Agent Showcase & Examples
+Build compelling demos showing agents interacting with go-micro services in realistic scenarios.
+
+### Priority 2: Additional Protocol Support
+- gRPC reflection-based MCP
+- HTTP/3 support
+
+### Priority 3: Kubernetes & Deployment
+- Helm Charts for MCP gateway
+- Kubernetes Operator with CRDs
+
+### Recently Completed
+- **Agent Plan & Delegate** - Two built-in agent tools: `plan` (ordered plan persisted to store-backed memory, surfaced in the prompt) and `delegate` (hand a subtask to another agent — RPC to a registered agent, else an ephemeral sub-agent with isolated context). Added automatically to every agent; no harness or graph. (`agent/builtin.go`, `examples/agent-plan-delegate/`)
+- **`micro new` MCP Templates** - Scaffolds MCP-enabled services with doc comments, `@example` tags, `WithMCP()`. `--no-mcp` to opt out.
+- **CRUD Example** - Contact book service with 6 operations, rich agent docs (`examples/mcp/crud/`)
+- **Migration Guide** - "Add MCP to Existing Services" guide with 3 approaches
+- **Troubleshooting Guide** - Common MCP issues and solutions
+- **Error Handling Guide** - Patterns for agent-friendly error responses
+- **Documentation Guides** - Six guides: AI-native services, MCP security, tool descriptions, agent patterns, error handling, troubleshooting
+- **WithMCP Option** - One-line MCP setup (`gateway/mcp/option.go`)
+- **Agent Playground Redesign** - Chat-focused UI with collapsible tool calls
+- **Standalone Gateway Binary** - `micro-mcp-gateway` with Docker support
+- **WebSocket Transport** - Bidirectional JSON-RPC 2.0 streaming (`gateway/mcp/websocket.go`)
+- **OpenTelemetry Integration** - Full span instrumentation with W3C trace context (`gateway/mcp/otel.go`)
+- **LlamaIndex SDK** - Python package with RAG examples (`contrib/go-micro-llamaindex/`)
+
+## Key Files
+
+| Purpose | File |
+|---------|------|
+| MCP Gateway | `gateway/mcp/mcp.go` |
+| MCP Docs | `gateway/mcp/DOCUMENTATION.md` |
+| AI Interface | `ai/model.go` |
+| Model Layer | `model/model.go` |
+| CLI Entry | `cmd/micro/main.go` |
+| MCP CLI | `cmd/micro/mcp/` |
+| Server (run/server) | `cmd/micro/server/server.go` |
+| Roadmap | `ROADMAP.md` (full: `internal/website/docs/roadmap.md`) |
+| Status | `CHANGELOG.md` |
+| Changelog | `CHANGELOG.md` |
+| Docs Site | `internal/website/docs/` |
+
+## Roadmap & Status Documents
+
+- **[ROADMAP.md](ROADMAP.md)** - the single, current roadmap (agentic development + DX). Full version at `internal/website/docs/roadmap.md`.
+- **[CHANGELOG.md](CHANGELOG.md)** - what shipped and when (the source of truth for status).
+- **[internal/docs/IMPLEMENTATION_SUMMARY.md](internal/docs/IMPLEMENTATION_SUMMARY.md)** - Implementation notes
+- **[CHANGELOG.md](CHANGELOG.md)** - What changed and when
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines. Key points:
+- Open an issue before large changes
+- Include tests for new features
+- Run `make test` and `make lint` before submitting
+- Follow commit message format: `type: description` (e.g., `feat: add WebSocket transport`)

CURRENT_STATUS_SUMMARY.md

@@ -1,282 +0,0 @@
-# Go Micro - Current Status Summary
-**Updated:** February 11, 2026
-
-## 🎯 Executive Summary
-
-**Go Micro's MCP integration is 3-4 months ahead of schedule**, with Q1 2026 goals complete and significant Q2/Q3 2026 features already delivered.
-
-### Quick Status
-- ✅ **Q1 2026 (MCP Foundation):** 100% COMPLETE
-- 🟢 **Q2 2026 (Agent DX):** 60% COMPLETE (ahead of schedule)
-- 🟢 **Q3 2026 (Production):** 40% COMPLETE (ahead of schedule)
-- 🟡 **Q4 2026 (Ecosystem):** 0% COMPLETE (on track)
-
----
-
-## 📊 What's Been Built
-
-### ✅ Core MCP Integration (Q1 - COMPLETE)
-- **MCP Gateway Library** (`gateway/mcp/`) - 2,083 lines
-  - HTTP/SSE transport
-  - Stdio JSON-RPC 2.0 transport
-  - Service discovery & tool generation
-  - Schema generation from Go types
-  
-- **CLI Commands** (`micro mcp`)
-  - `micro mcp serve` - Start MCP server (stdio or HTTP)
-  - `micro mcp list` - List available tools
-  - `micro mcp test` - Test tools (placeholder)
-
-- **Documentation**
-  - Complete API documentation
-  - 2 working examples (hello, documented)
-  - Blog post: "Making Microservices AI-Native with MCP"
-
-### ✅ Advanced Features (Q2/Q3 - DELIVERED EARLY)
-
-#### 🔒 Security & Auth
-- **Per-Tool Scopes**
-  - Service-level: `server.WithEndpointScopes("Blog.Create", "blog:write")`
-  - Gateway-level: `Options.Scopes` map for overrides
-  - Bearer token authentication
-  - Scope enforcement before RPC execution
-
-#### 📊 Observability
-- **Tracing**
-  - UUID trace IDs per tool call
-  - Metadata propagation (`Mcp-Trace-Id`, `Mcp-Tool-Name`, `Mcp-Account-Id`)
-  - Full call chain tracking
-
-- **Audit Logging**
-  - Immutable audit records per tool call
-  - Captures: tool, account, scopes, allowed/denied, duration, errors
-  - Callback function: `Options.AuditFunc`
-
-#### 🚦 Rate Limiting
-- Per-tool rate limiters
-- Configurable requests/second and burst
-- Token bucket algorithm
-
-#### 📝 Documentation Extraction
-- Auto-extract from Go doc comments
-- `@example` tag support for JSON examples
-- Struct tag parsing for parameter descriptions
-- Manual override via `WithEndpointDocs()`
-
----
-
-## 🚀 What Works Today
-
-### For Claude Code Users
-```bash
-# Start MCP server for Claude Code
-micro mcp serve
-
-# Add to ~/.claude/claude_desktop_config.json:
-{
-  "mcpServers": {
-    "my-services": {
-      "command": "micro",
-      "args": ["mcp", "serve"]
-    }
-  }
-}
-```
-
-### For Library Users
-```go
-package main
-
-import (
-    "go-micro.dev/v5"
-    "go-micro.dev/v5/gateway/mcp"
-)
-
-func main() {
-    service := micro.NewService(micro.Name("myservice"))
-    service.Init()
-
-    // Add MCP gateway (3 lines!)
-    go mcp.ListenAndServe(":3000", mcp.Options{
-        Registry: service.Options().Registry,
-        Auth:     authProvider,  // Optional: auth.Auth
-        Scopes: map[string][]string{  // Optional: per-tool scopes
-            "myservice.Handler.Create": {"write"},
-        },
-        RateLimit: &mcp.RateLimitConfig{  // Optional
-            RequestsPerSecond: 10,
-            Burst:             20,
-        },
-        AuditFunc: func(r mcp.AuditRecord) {  // Optional
-            log.Printf("[audit] %+v", r)
-        },
-    })
-
-    service.Run()
-}
-```
-
-### For Service Developers
-```go
-// Just add Go comments - docs extracted automatically!
-
-// GetUser retrieves a user by ID. Returns full profile with email and preferences.
-//
-// @example {"id": "user-123"}
-func (s *UserService) GetUser(ctx context.Context, req *GetUserRequest, rsp *GetUserResponse) error {
-    // implementation
-}
-
-// Register with scopes
-handler := service.Server().NewHandler(
-    new(UserService),
-    server.WithEndpointScopes("UserService.Delete", "users:admin"),
-)
-```
-
----
-
-## 📈 Test Coverage
-
-**568 lines** of comprehensive tests covering:
-- ✅ Scope validation & enforcement
-- ✅ Auth provider integration
-- ✅ Trace ID generation & propagation
-- ✅ Audit record creation
-- ✅ Rate limiting
-- ✅ HTTP & Stdio transports
-- ✅ Tool discovery & schema generation
-
----
-
-## 🎯 What's Next (Recommended Priorities)
-
-### Immediate (Next 2 Weeks)
-1. **Complete `micro mcp test` command** (~1 day)
-   - Implement actual tool testing with JSON input/output
-   
-2. **LangChain SDK** (~1 week)
-   - Python package: `go-micro-langchain`
-   - Auto-generate LangChain tools from registry
-   - Example multi-agent workflow
-   - **Impact:** Largest agent framework integration
-
-3. **Interactive Playground** (~1 week)
-   - Web UI for testing services with AI
-   - Real-time tool call visualization
-   - **Impact:** Critical for demos and sales
-
-### Short-Term (Next Month)
-4. **WebSocket Transport** (~3 days)
-   - Bidirectional streaming for long-running operations
-   
-5. **LlamaIndex SDK** (~1 week)
-   - Python package for RAG integration
-   
-6. **Case Studies** (ongoing)
-   - Document real-world usage
-
----
-
-## 📊 By The Numbers
-
-| Metric | Value |
-|--------|-------|
-| **Production Code** | 2,083 lines |
-| **Test Code** | 568 lines |
-| **Documentation Files** | 4+ |
-| **Working Examples** | 2 |
-| **CLI Commands** | 3 |
-| **Transports** | 2 (HTTP/SSE, Stdio) |
-| **Q1 Completion** | 100% |
-| **Ahead of Schedule** | 3-4 months |
-
----
-
-## 🔍 Where We Are on the Roadmap
-
-### Q1 2026: MCP Foundation
-**Status:** ✅ COMPLETE (100%)
-- All 6 planned deliverables complete
-- Production-ready implementation
-- Comprehensive documentation
-
-### Q2 2026: Agent Developer Experience  
-**Status:** 🟢 IN PROGRESS (60% complete)
-
-**COMPLETED (ahead of schedule):**
-- ✅ Stdio transport for Claude Code
-- ✅ `micro mcp serve` and `list` commands
-- ✅ Tool descriptions from comments
-- ✅ `@example` tag support
-- ✅ Schema generation from struct tags
-- ✅ HTTP/SSE with auth
-
-**NOT YET STARTED:**
-- ❌ `micro mcp test` (full implementation)
-- ❌ `micro mcp docs` and `export` commands
-- ❌ Agent SDKs (LangChain, LlamaIndex, AutoGPT)
-- ❌ Interactive Agent Playground
-- ❌ Multi-protocol (WebSocket, gRPC, HTTP/3)
-
-### Q3 2026: Production & Scale
-**Status:** 🟢 IN PROGRESS (40% complete)
-
-**COMPLETED (ahead of schedule):**
-- ✅ Per-tool authentication & scopes
-- ✅ Agent call tracing
-- ✅ Rate limiting
-- ✅ Audit logging
-- ✅ Bearer token auth
-
-**NOT YET STARTED:**
-- ❌ Standalone MCP Gateway binary
-- ❌ Kubernetes Operator
-- ❌ Helm Charts
-- ❌ OpenTelemetry integration
-- ❌ Full observability dashboards
-
-### Q4 2026: Ecosystem & Monetization
-**Status:** 🟡 PLANNING (0% complete)
-- All features planned for Q4 2026
-- On track to start in Q4
-
----
-
-## 📖 Key Documents
-
-1. **[PROJECT_STATUS_2026.md](./PROJECT_STATUS_2026.md)** - Comprehensive 20-page status report
-2. **[ROADMAP_2026.md](./ROADMAP_2026.md)** - Updated roadmap with completion markers
-3. **[/gateway/mcp/DOCUMENTATION.md](./gateway/mcp/DOCUMENTATION.md)** - Complete MCP documentation
-4. **[/examples/mcp/README.md](./examples/mcp/README.md)** - Examples and usage guide
-5. **[/internal/website/blog/2.md](./internal/website/blog/2.md)** - Launch blog post
-
----
-
-## 🎉 Key Achievements
-
-1. **✅ Production-Ready in Q1** - Ahead of schedule
-2. **✅ Security-First** - Auth, scopes, audit from day one
-3. **✅ Developer-Friendly** - 3 lines of code to enable MCP
-4. **✅ Claude Code Ready** - Works with Anthropic's flagship IDE
-5. **✅ Comprehensive Testing** - 90%+ test coverage
-6. **✅ Well-Documented** - Multiple docs + examples + blog post
-
----
-
-## 💡 Bottom Line
-
-**Go Micro is production-ready for AI agent integration TODAY.**
-
-The Q1 2026 foundation is solid, with advanced Q2/Q3 features already delivered. The framework is:
-- ✅ Ready for production use
-- ✅ Secure by default
-- ✅ Easy to use (3 lines of code)
-- ✅ Well-tested and documented
-- ✅ Compatible with Claude Code and other AI tools
-
-**Next focus:** Agent SDKs and developer tools to drive adoption.
-
----
-
-**For detailed technical analysis, see [PROJECT_STATUS_2026.md](./PROJECT_STATUS_2026.md)**

Dockerfile

@@ -0,0 +1,26 @@
+FROM alpine:latest
+ARG TARGETPLATFORM
+ENV USER=micro
+ENV GROUPNAME=$USER
+ARG UID=1001
+ARG GID=1001
+RUN addgroup --gid "$GID" "$GROUPNAME" \
+    && adduser \
+    --disabled-password \
+    --gecos "" \
+    --home "/micro" \
+    --ingroup "$GROUPNAME" \
+    --no-create-home \
+    --uid "$UID" "$USER"
+
+ENV PATH=/usr/local/go/bin:$PATH
+RUN apk --no-cache add git make curl
+COPY --from=golang:1.26.0-alpine /usr/local/go /usr/local/go
+
+COPY $TARGETPLATFORM/micro /usr/local/go/bin/
+COPY $TARGETPLATFORM/protoc-gen-micro /usr/local/go/bin/
+
+WORKDIR /micro
+EXPOSE 8080
+ENTRYPOINT ["/usr/local/go/bin/micro"]
+CMD ["server"]

Makefile

@@ -1,4 +1,14 @@
-.PHONY: test test-race test-coverage lint fmt install-tools proto clean help
+NAME = micro
+GIT_COMMIT = $(shell git rev-parse --short HEAD)
+GIT_TAG = $(shell git describe --abbrev=0 --tags --always --match "v*")
+GIT_IMPORT = go-micro.dev/v5/cmd/micro
+BUILD_DATE = $(shell date +%s)
+LDFLAGS = -X $(GIT_IMPORT).BuildDate=$(BUILD_DATE) -X $(GIT_IMPORT).GitCommit=$(GIT_COMMIT) -X $(GIT_IMPORT).GitTag=$(GIT_TAG)
+
+# 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
 
 # Default target
 help:
@@ -13,6 +23,9 @@ help:
 	@echo "  make proto         - Generate protobuf code"
 	@echo "  make clean         - Clean build artifacts"
 
+$(NAME):
+	CGO_ENABLED=0 go build -ldflags "-s -w ${LDFLAGS}" -o $(NAME) cmd/micro/main.go
+
 # Run tests
 test:
 	go test -v ./...
@@ -27,6 +40,13 @@ test-coverage:
 	go tool cover -html=coverage.out -o coverage.html
 	@echo "Coverage report: coverage.html"
 
+# Run the end-to-end harnesses (deterministic, mock LLM — no API key).
+# The universe harness exits non-zero on assertion failure.
+harness:
+	go run ./internal/harness/universe
+	go run ./internal/harness/agent-flow
+	go run ./internal/harness/plan-delegate
+
 # Run linter
 lint:
 	golangci-lint run
@@ -56,3 +76,14 @@ clean:
 	find . -name "*.test" -type f -delete
 	go clean -cache -testcache
 
+# Try binary release
+gorelease-dry-run:
+	docker run \
+		--rm \
+		-e CGO_ENABLED=0 \
+		-v $(CURDIR):/$(NAME) \
+		-v /var/run/docker.sock:/var/run/docker.sock \
+		-w /$(NAME) \
+		$(GORELEASER_DOCKER_IMAGE) \
+		--clean --verbose --skip=publish,validate --snapshot
+

PROJECT_STATUS_2026.md

@@ -1,727 +0,0 @@
-# Go Micro Project Status - February 2026
-## MCP Integration and Tool Scopes Implementation
-
-**Date:** February 11, 2026  
-**Analysis Period:** Q1 2026 Roadmap Items + Recent Commits  
-**Focus Areas:** MCP Integration, Tool Scopes, CLI Integration
-
----
-
-## Executive Summary
-
-The **Q1 2026: MCP Foundation** milestone is **COMPLETE** with significant progress beyond the original roadmap. The implementation includes not only the planned Q1 features but also several Q2 2026 features, particularly around **tool scopes**, **authentication**, **tracing**, and **rate limiting**.
-
-### Status at a Glance
-
-| Category | Status | Completion |
-|----------|--------|------------|
-| **Q1 2026: MCP Foundation** | ✅ COMPLETE | 100% |
-| **Tool Scopes (Q2 Feature)** | ✅ COMPLETE | 100% |
-| **Stdio Transport (Q2 Feature)** | ✅ COMPLETE | 100% |
-| **CLI Integration** | ✅ COMPLETE | 100% |
-| **Documentation Extraction** | ✅ COMPLETE | 100% |
-| **Tracing & Audit** | ✅ COMPLETE | 100% |
-| **Rate Limiting** | ✅ COMPLETE | 100% |
-
----
-
-## Q1 2026: MCP Foundation - COMPLETE ✅
-
-All planned Q1 2026 deliverables have been completed:
-
-### ✅ MCP Library (`gateway/mcp`)
-- **Status:** COMPLETE
-- **Location:** `/gateway/mcp/`
-- **Files:**
-  - `mcp.go` (630 lines) - Core MCP gateway implementation
-  - `stdio.go` (369 lines) - Stdio JSON-RPC 2.0 transport
-  - `parser.go` (339 lines) - Documentation extraction
-  - `ratelimit.go` (51 lines) - Rate limiting
-  - `mcp_test.go` (568 lines) - Comprehensive test suite
-  - `example_test.go` (126 lines) - Usage examples
-  - `DOCUMENTATION.md` - Complete documentation
-
-**Features Implemented:**
-- Service discovery from registry
-- Automatic tool generation from endpoints
-- HTTP/SSE transport
-- Stdio transport (JSON-RPC 2.0)
-- Authentication with auth.Auth integration
-- Per-tool scope enforcement
-- Trace ID generation and propagation
-- Rate limiting (configurable per-tool)
-- Audit logging with AuditFunc callback
-- Schema generation from Go types
-
-### ✅ CLI Integration (`micro mcp`)
-- **Status:** COMPLETE
-- **Location:** `/cmd/micro/mcp/mcp.go`
-- **Commands Implemented:**
-  - `micro mcp serve` - Start MCP server (stdio or HTTP)
-  - `micro mcp serve --address :3000` - HTTP/SSE mode
-  - `micro mcp list` - List available tools
-  - `micro mcp test <tool>` - Test tool (placeholder)
-
-**CLI Features:**
-- Registry integration (mdns default)
-- Graceful shutdown handling
-- JSON output support for `list` command
-- Human-readable output
-
-### ✅ Service Discovery and Tool Generation
-- **Status:** COMPLETE
-- **Implementation:**
-  - Automatic service discovery via registry
-  - Tools generated from endpoint metadata
-  - Dynamic tool updates via registry watcher
-  - Support for service metadata extraction
-
-### ✅ HTTP/SSE Transport
-- **Status:** COMPLETE
-- **Endpoints:**
-  - `GET /mcp/tools` - List available tools
-  - `POST /mcp/call` - Call a tool
-  - `GET /health` - Health check
-- **Features:**
-  - Server-Sent Events (SSE) ready
-  - Authentication via Bearer tokens
-  - Trace ID generation
-  - Audit logging
-
-### ✅ Documentation and Examples
-- **Status:** COMPLETE
-- **Documentation:**
-  - `/gateway/mcp/DOCUMENTATION.md` - Complete MCP documentation
-  - `/examples/mcp/README.md` - Examples with usage guide
-  - `/internal/website/docs/mcp.md` - Website documentation
-  - `/internal/website/docs/roadmap-2026.md` - Updated roadmap
-- **Examples:**
-  - `/examples/mcp/hello/` - Minimal example
-  - `/examples/mcp/documented/` - Full-featured example with auth scopes
-
-### ✅ Blog Post and Launch
-- **Status:** COMPLETE
-- **Location:** `/internal/website/blog/2.md`
-- **Title:** "Making Microservices AI-Native with MCP"
-- **Published:** February 11, 2026
-
----
-
-## Beyond Q1: Advanced Features Already Implemented
-
-### ✅ Per-Tool Auth Scopes (Q2 2026 Feature)
-
-**Status:** COMPLETE (ahead of schedule)
-
-This was planned for Q2 2026 but has been fully implemented:
-
-#### Implementation Details:
-
-1. **Service-Level Scopes** via `server.WithEndpointScopes()`
-   ```go
-   handler := service.Server().NewHandler(
-       new(BlogService),
-       server.WithEndpointScopes("Blog.Create", "blog:write"),
-       server.WithEndpointScopes("Blog.Delete", "blog:admin"),
-   )
-   ```
-
-2. **Gateway-Level Scope Overrides** via `mcp.Options.Scopes`
-   ```go
-   mcp.Serve(mcp.Options{
-       Registry: reg,
-       Auth:     authProvider,
-       Scopes: map[string][]string{
-           "blog.Blog.Create": {"blog:write"},
-           "blog.Blog.Delete": {"blog:admin"},
-       },
-   })
-   ```
-
-3. **Auth Integration:**
-   - `Options.Auth` field for auth.Auth provider
-   - Bearer token inspection
-   - Account scope validation
-   - Scope enforcement before RPC execution
-
-4. **Metadata Storage:**
-   - Scopes stored in endpoint metadata (`"scopes"` key)
-   - Comma-separated values propagated via registry
-   - Gateway-level scopes take precedence
-
-**Test Coverage:**
-- `TestHasScope` - Scope matching logic
-- `TestToolScopesFromMetadata` - Scope extraction
-- `TestHandleCallTool_AuthRequired` - Auth enforcement
-- `TestHandleCallTool_Audit_Allowed` - Audit with auth
-- `TestHandleCallTool_Audit_Denied` - Audit denied calls
-
-### ✅ Stdio Transport for Claude Code (Q2 2026 Feature)
-
-**Status:** COMPLETE (ahead of schedule)
-
-This was planned for Q2 2026 but has been fully implemented:
-
-#### Implementation Details:
-
-1. **JSON-RPC 2.0 Protocol:**
-   - Full JSON-RPC 2.0 compliance
-   - Standard error codes (ParseError, InvalidRequest, etc.)
-   - Request/response ID tracking
-
-2. **MCP Methods Supported:**
-   - `initialize` - Protocol handshake
-   - `tools/list` - List available tools
-   - `tools/call` - Execute a tool
-
-3. **Transport Features:**
-   - Stdin/stdout communication
-   - Line-buffered JSON
-   - Concurrent request handling
-   - Graceful shutdown
-
-4. **CLI Integration:**
-   ```bash
-   # For Claude Code
-   micro mcp serve
-   
-   # Claude Code config
-   {
-     "mcpServers": {
-       "my-services": {
-         "command": "micro",
-         "args": ["mcp", "serve"]
-       }
-     }
-   }
-   ```
-
-### ✅ Tool Documentation from Comments (Q2 2026 Feature)
-
-**Status:** COMPLETE (ahead of schedule)
-
-This was planned for Q2 2026 but has been fully implemented:
-
-#### Implementation Details:
-
-1. **Automatic Extraction:**
-   - Go doc comments → Tool descriptions
-   - `@example` tags → Example JSON inputs
-   - Struct tags → Parameter descriptions
-
-2. **Parser Features (`parser.go`):**
-   - Comment parsing on handler registration
-   - Example extraction with `@example` tag
-   - Metadata propagation via registry
-
-3. **Example:**
-   ```go
-   // GetUser retrieves a user by ID. Returns full profile.
-   //
-   // @example {"id": "user-123"}
-   func (s *UserService) GetUser(ctx context.Context, req *GetUserRequest, rsp *GetUserResponse) error {
-       // implementation
-   }
-   ```
-
-4. **Manual Override Support:**
-   ```go
-   server.WithEndpointDocs(map[string]server.EndpointDoc{
-       "UserService.GetUser": {
-           Description: "Custom description",
-           Example:     `{"id": "user-123"}`,
-       },
-   })
-   ```
-
-### ✅ Tracing (Q3 2026 Feature)
-
-**Status:** COMPLETE (ahead of schedule)
-
-This was planned for Q3 2026 but has been fully implemented:
-
-#### Implementation Details:
-
-1. **Trace ID Generation:**
-   - UUID-based trace IDs
-   - Generated per tool call
-   - Propagated via metadata
-
-2. **Metadata Propagation:**
-   - `Mcp-Trace-Id` - Trace identifier
-   - `Mcp-Tool-Name` - Tool being invoked
-   - `Mcp-Account-Id` - Authenticated account
-
-3. **Context Injection:**
-   - Trace metadata added to RPC context
-   - Accessible to downstream services
-   - Full call chain tracking
-
-### ✅ Rate Limiting (Q3 2026 Feature)
-
-**Status:** COMPLETE (ahead of schedule)
-
-This was planned for Q3 2026 but has been fully implemented:
-
-#### Implementation Details:
-
-1. **Configuration:**
-   ```go
-   mcp.Serve(mcp.Options{
-       Registry: reg,
-       RateLimit: &mcp.RateLimitConfig{
-           RequestsPerSecond: 10,
-           Burst:             20,
-       },
-   })
-   ```
-
-2. **Implementation:**
-   - Per-tool rate limiters
-   - Token bucket algorithm
-   - Configurable requests/second and burst
-   - 429 Too Many Requests response
-
-3. **File:** `ratelimit.go` (51 lines)
-
-### ✅ Audit Logging (Q3 2026 Feature)
-
-**Status:** COMPLETE (ahead of schedule)
-
-This was planned for Q3 2026 but has been fully implemented:
-
-#### Implementation Details:
-
-1. **AuditRecord Structure:**
-   ```go
-   type AuditRecord struct {
-       TraceID        string
-       Timestamp      time.Time
-       Tool           string
-       AccountID      string
-       ScopesRequired []string
-       Allowed        bool
-       DeniedReason   string
-       Duration       time.Duration
-       Error          string
-   }
-   ```
-
-2. **Callback Function:**
-   ```go
-   mcp.Serve(mcp.Options{
-       Registry: reg,
-       AuditFunc: func(r mcp.AuditRecord) {
-           log.Printf("[audit] trace=%s tool=%s allowed=%v",
-               r.TraceID, r.Tool, r.Allowed)
-       },
-   })
-   ```
-
-3. **Features:**
-   - Immutable audit records
-   - Capture allowed and denied calls
-   - Include auth context
-   - Record RPC duration and errors
-
----
-
-## Recent Commits Analysis
-
-### Primary Commit: ac47a46
-**Title:** "MCP gateway: add per-tool scopes, tracing, rate limiting, and audit logging"  
-**PR:** #2850  
-**Date:** February 11, 2026
-
-**Changes:**
-- Added `Scopes` field to `Tool` struct
-- Added `Auth` (auth.Auth) integration to `Options`
-- Added trace ID generation (UUID) with metadata propagation
-- Added per-tool rate limiting (configurable requests/sec and burst)
-- Added `AuditFunc` callback for audit records
-- Extracted tool scopes from endpoint metadata ("scopes" key)
-- Updated both HTTP and stdio transports with auth/trace/rate/audit
-- Added `server.WithEndpointScopes()` helper
-- Added gateway-level `Options.Scopes` for overrides
-- Comprehensive test suite for all new features
-- Updated documentation and examples
-
-**Impact:**
-- Brought multiple Q2/Q3 2026 features forward
-- Production-ready security features
-- Enterprise-grade observability
-
----
-
-## Feature Comparison: Planned vs. Actual
-
-### Q2 2026 Features - Early Delivery
-
-| Feature | Roadmap Status | Actual Status | Notes |
-|---------|----------------|---------------|-------|
-| Stdio Transport | Planned Q2 | ✅ COMPLETE | Full JSON-RPC 2.0 implementation |
-| `micro mcp` commands | Planned Q2 | ✅ COMPLETE | `serve`, `list`, `test` (partial) |
-| Tool descriptions from comments | Planned Q2 | ✅ COMPLETE | Auto-extraction working |
-| `@example` tag support | Planned Q2 | ✅ COMPLETE | Implemented in parser |
-| Schema from struct tags | Planned Q2 | ✅ COMPLETE | Type mapping implemented |
-
-### Q2 2026 Features - Not Yet Implemented
-
-| Feature | Status | Priority |
-|---------|--------|----------|
-| `micro mcp test` full implementation | 🟡 Partial | Medium |
-| `micro mcp docs` command | ❌ Not Started | Low |
-| `micro mcp export` commands | ❌ Not Started | Low |
-| Multi-protocol support (WebSocket, gRPC, HTTP/3) | ❌ Not Started | Medium |
-| Agent SDKs (LangChain, LlamaIndex) | ❌ Not Started | High |
-| Interactive Agent Playground | ❌ Not Started | High |
-
-### Q3 2026 Features - Early Delivery
-
-| Feature | Roadmap Status | Actual Status | Notes |
-|---------|----------------|---------------|-------|
-| Tracing | Planned Q3 | ✅ COMPLETE | UUID trace IDs |
-| Rate Limiting | Planned Q3 | ✅ COMPLETE | Per-tool limiters |
-| Audit Logging | Planned Q3 | ✅ COMPLETE | Full audit records |
-| Auth Integration | Planned Q3 | ✅ COMPLETE | Bearer tokens + scopes |
-
----
-
-## Test Coverage
-
-### Comprehensive Test Suite (`mcp_test.go` - 568 lines)
-
-**Tests Implemented:**
-1. `TestHasScope` - Scope matching logic
-2. `TestToolScopesFromMetadata` - Scope extraction from registry
-3. `TestHandleCallTool_AuthRequired` - Auth enforcement
-4. `TestHandleCallTool_TraceID` - Trace ID generation
-5. `TestHandleCallTool_Audit_Allowed` - Audit for allowed calls
-6. `TestHandleCallTool_Audit_Denied` - Audit for denied calls
-7. `TestRateLimit` - Rate limiting behavior
-
-**Test Coverage Areas:**
-- ✅ Scope validation
-- ✅ Auth provider integration
-- ✅ Trace ID propagation
-- ✅ Audit record generation
-- ✅ Rate limiting
-- ✅ HTTP transport
-- ✅ Stdio transport
-- ✅ Tool discovery
-- ✅ Schema generation
-
----
-
-## Documentation Status
-
-### ✅ Complete Documentation
-
-1. **Gateway Documentation** (`gateway/mcp/DOCUMENTATION.md`)
-   - Automatic documentation extraction
-   - Manual registration methods
-   - Endpoint scopes configuration
-   - Gateway-level scope overrides
-
-2. **Examples README** (`examples/mcp/README.md`)
-   - Quick start guide
-   - Multiple transports (stdio, HTTP)
-   - Auth scopes examples
-   - Tracing, rate limiting, audit examples
-   - CLI usage
-
-3. **Website Documentation** (`internal/website/docs/mcp.md`)
-   - Full MCP integration guide
-
-4. **Blog Post** (`internal/website/blog/2.md`)
-   - "Making Microservices AI-Native with MCP"
-   - Published February 11, 2026
-
-5. **Examples:**
-   - `examples/mcp/hello/` - Minimal working example
-   - `examples/mcp/documented/` - Full-featured example with scopes
-
----
-
-## Current Implementation Status by Component
-
-### Core MCP Gateway (`gateway/mcp/`)
-
-| Component | Status | Lines | Completeness |
-|-----------|--------|-------|--------------|
-| `mcp.go` | ✅ Production | 630 | 100% |
-| `stdio.go` | ✅ Production | 369 | 100% |
-| `parser.go` | ✅ Production | 339 | 100% |
-| `ratelimit.go` | ✅ Production | 51 | 100% |
-| `mcp_test.go` | ✅ Complete | 568 | 100% |
-| `example_test.go` | ✅ Complete | 126 | 100% |
-| `DOCUMENTATION.md` | ✅ Complete | - | 100% |
-
-**Total Lines:** 2,083 (excluding docs)
-
-### CLI Integration (`cmd/micro/mcp/`)
-
-| Component | Status | Completeness |
-|-----------|--------|--------------|
-| `mcp.go` | ✅ Production | 90% |
-| `serve` command | ✅ Complete | 100% |
-| `list` command | ✅ Complete | 100% |
-| `test` command | 🟡 Placeholder | 20% |
-
-### Server Integration (`server/`)
-
-| Component | Status | Completeness |
-|-----------|--------|--------------|
-| `WithEndpointScopes()` | ✅ Complete | 100% |
-| `WithEndpointDocs()` | ✅ Complete | 100% |
-| Comment extraction | ✅ Complete | 100% |
-
----
-
-## Roadmap Progress Summary
-
-### Q1 2026: MCP Foundation
-**Status:** ✅ COMPLETE (100%)
-
-All planned features delivered:
-- MCP library ✅
-- CLI integration ✅
-- Service discovery ✅
-- HTTP/SSE transport ✅
-- Documentation ✅
-- Blog post ✅
-
-### Q2 2026: Agent Developer Experience
-**Status:** 🟢 Ahead of Schedule (60% complete)
-
-**Completed (ahead of schedule):**
-- ✅ Stdio transport for Claude Code
-- ✅ `micro mcp` command suite (partial)
-- ✅ Tool descriptions from comments
-- ✅ `@example` tag support
-- ✅ Schema generation from struct tags
-
-**Not Started:**
-- ❌ Multi-protocol support (WebSocket, gRPC)
-- ❌ Agent SDKs (LangChain, LlamaIndex)
-- ❌ Interactive Agent Playground
-- ❌ Export commands
-
-### Q3 2026: Production & Scale
-**Status:** 🟢 Ahead of Schedule (40% complete)
-
-**Completed (ahead of schedule):**
-- ✅ Per-tool authentication
-- ✅ Scope-based permissions
-- ✅ Tracing with trace IDs
-- ✅ Rate limiting
-- ✅ Audit logging
-
-**Not Started:**
-- ❌ Enterprise MCP Gateway (standalone binary)
-- ❌ Kubernetes Operator
-- ❌ Helm Charts
-- ❌ Full observability dashboards
-
-### Q4 2026: Ecosystem & Monetization
-**Status:** 🟡 Planning Phase (0% complete)
-
-All features planned for Q4 2026.
-
----
-
-## Key Achievements
-
-### 🎯 Accelerated Development
-- **3-4 months ahead of schedule** on core features
-- Q2 2026 features (stdio, scopes) delivered in Q1
-- Q3 2026 features (auth, tracing, rate limiting) delivered in Q1
-
-### 🔒 Production-Ready Security
-- Full auth.Auth integration
-- Per-tool scope enforcement
-- Audit trail for compliance
-- Rate limiting for protection
-
-### 📚 Comprehensive Documentation
-- 4+ documentation files
-- 2 working examples
-- Blog post published
-- In-code examples
-
-### 🧪 Robust Testing
-- 568 lines of tests
-- Auth testing with mock provider
-- Scope enforcement validation
-- Audit record verification
-- Rate limiting tests
-
----
-
-## Areas for Improvement
-
-### 1. CLI Testing (`micro mcp test`)
-**Status:** Placeholder implementation  
-**Priority:** Medium  
-**Effort:** ~1 day
-
-Current implementation:
-```go
-func testAction(ctx *cli.Context) error {
-    // ...
-    fmt.Println("(Not yet implemented - coming soon)")
-    return nil
-}
-```
-
-**Recommendation:** Implement actual tool testing with:
-- JSON input validation
-- RPC call execution
-- Response formatting
-- Error handling
-
-### 2. Agent SDKs (Q2 2026)
-**Status:** Not started  
-**Priority:** High  
-**Effort:** ~2 weeks per SDK
-
-**Recommended order:**
-1. LangChain (largest ecosystem)
-2. LlamaIndex (RAG/data focus)
-3. AutoGPT (autonomous agents)
-
-### 3. Interactive Playground (Q2 2026)
-**Status:** Not started  
-**Priority:** High (for demos)  
-**Effort:** ~1 week
-
-**Value:** Critical for:
-- Product demos
-- Developer onboarding
-- Testing tool integrations
-
-### 4. Multi-Protocol Support (Q2 2026)
-**Status:** Not started  
-**Priority:** Medium  
-**Effort:** ~1 week per protocol
-
-**Protocols to add:**
-- WebSocket (bidirectional streaming)
-- gRPC (reflection-based)
-- HTTP/3 (performance)
-
----
-
-## Recommendations
-
-### Immediate Actions (Next 2 Weeks)
-
-1. **Complete `micro mcp test` command** (~1 day)
-   - Implement actual tool testing
-   - Add JSON validation
-   - Format responses properly
-
-2. **Create LangChain SDK** (~1 week)
-   - Python package `go-micro-langchain`
-   - Auto-generate LangChain tools
-   - Example multi-agent workflow
-   - **Impact:** Largest agent framework integration
-
-3. **Build Interactive Playground** (~1 week)
-   - Web UI for testing services
-   - Real-time tool call visualization
-   - Embeddable in `micro run` dashboard
-   - **Impact:** Critical for demos and sales
-
-### Short-Term (Next Month)
-
-4. **Add WebSocket Transport** (~3 days)
-   - Bidirectional streaming
-   - Better for long-running operations
-   - Agent feedback loops
-
-5. **Create LlamaIndex SDK** (~1 week)
-   - Python package `go-micro-llamaindex`
-   - Service discovery as data sources
-   - RAG integration example
-
-6. **Publish Case Studies** (~ongoing)
-   - Document real-world usage
-   - Share on blog
-   - Community testimonials
-
-### Medium-Term (Next Quarter)
-
-7. **Enterprise MCP Gateway** (Q3 feature)
-   - Standalone binary
-   - Horizontal scaling
-   - Production observability
-
-8. **Kubernetes Operator** (Q3 feature)
-   - CRD for MCPGateway
-   - Auto-scaling
-   - Service mesh integration
-
----
-
-## Success Metrics
-
-### Technical KPIs - Current Status
-
-| Metric | Target | Current | Status |
-|--------|--------|---------|--------|
-| Claude Desktop integration | 95%+ | ✅ 100% | ACHIEVED |
-| Tool discovery latency (p99) | <100ms | ✅ <50ms | EXCEEDED |
-| Stdio transport compliance | 100% | ✅ 100% | ACHIEVED |
-| Test coverage | >80% | ✅ 90%+ | EXCEEDED |
-
-### Implementation KPIs - Current Status
-
-| Metric | Target Q1 | Current | Status |
-|--------|-----------|---------|--------|
-| MCP library | ✅ Complete | ✅ Complete | ACHIEVED |
-| CLI integration | ✅ Complete | ✅ Complete | ACHIEVED |
-| Documentation | ✅ Complete | ✅ Complete | ACHIEVED |
-| Examples | 2+ | ✅ 2 | ACHIEVED |
-| Blog posts | 1+ | ✅ 1 | ACHIEVED |
-
----
-
-## Conclusion
-
-The **Q1 2026: MCP Foundation** milestone is **COMPLETE** with exceptional execution that has delivered features planned for Q2 and Q3 2026.
-
-### Key Highlights:
-
-1. **✅ 100% of Q1 deliverables** completed on schedule
-2. **✅ 60% of Q2 deliverables** completed early (stdio, scopes, docs)
-3. **✅ 40% of Q3 deliverables** completed early (auth, tracing, rate limiting, audit)
-4. **2,083 lines** of production MCP code
-5. **568 lines** of comprehensive tests
-6. **Full documentation** with examples and blog post
-
-### Production Readiness:
-
-The MCP integration is **production-ready** with:
-- ✅ Full auth.Auth integration
-- ✅ Per-tool scope enforcement
-- ✅ Tracing and audit logging
-- ✅ Rate limiting
-- ✅ Stdio transport for Claude Code
-- ✅ HTTP/SSE transport for web agents
-- ✅ Comprehensive test coverage
-
-### Next Steps:
-
-**Immediate priorities** to maintain momentum:
-1. Complete `micro mcp test` command (1 day)
-2. Build LangChain SDK (1 week)
-3. Create Interactive Playground (1 week)
-
-The project is **3-4 months ahead of the roadmap** and well-positioned to achieve the 2026-2027 goals of making go-micro the **standard microservices framework for the agent era**.
-
----
-
-**Report Generated:** February 11, 2026  
-**Analysis By:** Copilot Engineering Agent  
-**Status:** CURRENT

README.md

@@ -1,292 +1,407 @@
-# 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/v5?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 [![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 distributed systems development.
+Go Micro is a framework for building agents and services in Go.
 
-**[📖 Documentation](https://go-micro.dev/docs/)** | [Sponsor the project](https://github.com/sponsors/micro) | [Discord](https://discord.gg/jwTYuUVAGh)
+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.
 
-## Overview
+## Sponsors
 
-Go Micro provides the core requirements for distributed systems development including RPC and Event driven communication.
-The Go Micro philosophy is sane defaults with a pluggable architecture. We provide defaults to get you started quickly
-but everything can be easily swapped out.
+<a href="https://go-micro.dev/blog/3"><img src="https://upload.wikimedia.org/wikipedia/commons/7/78/Anthropic_logo.svg" height="26" /></a>
+&nbsp;&nbsp;
+<a href="https://go-micro.dev/blog/8"><img src="https://www.atlascloud.ai/logo.svg" height="26" /></a>
 
-## Features
+**Want to support Go Micro and see your logo here?** [Become a sponsor](https://discord.gg/WeMU5AGxD) — reach out on Discord.
 
-Go Micro abstracts away the details of distributed systems. Here are the main features.
+## Commercial Support
 
-- **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.
+Running Go Micro in production, or building on it and want help? Paid **support, consulting, training, and retainers** are available directly from the maintainer — and they're what keep the project maintained. See [**Support**](SUPPORT.md) for the tiers, or [open a request](https://github.com/micro/go-micro/issues/new?template=commercial_support.md).
 
-- **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.
+## Contents
 
-- **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.
+- [Quick Start](#quick-start)
+- [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)
+- [CLI](#cli)
+- [Multi-Service Projects](#multi-service-projects)
+- [Data Model](#data-model)
+- [AI Providers](#ai-providers)
+- [Examples](#examples)
+- [Commercial Support](#commercial-support)
+- [Docs](#docs)
 
-- **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.
+## Quick Start
 
-- **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.
-
-- **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.
-
-- **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.
-
-- **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.
-
-- **MCP Integration** - An MCP gateway you can integrate as a library, server or CLI command which automatically exposes services
-  as tools for agents or other AI applications. Every service/endpoint get's converted into a callable tool.
-
-- **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.
-
-## Getting Started
-
-To make use of Go Micro 
+Install the CLI:
 
 ```bash
-go get go-micro.dev/v5@latest
+# Binary (no Go required)
+curl -fsSL https://go-micro.dev/install.sh | sh
+
+# Or with Go
+go install go-micro.dev/v6/cmd/micro@v6
 ```
 
-Create a service and register a handler
+### Fastest start — no API key
+
+Scaffold a service, run it, call it:
+
+```bash
+micro new helloworld
+cd helloworld
+micro run
+```
+
+Then in another terminal:
+
+```bash
+curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \
+  -H 'Content-Type: application/json' -d '{"name":"World"}'
+```
+
+### Generate from a prompt — with an LLM key
+
+Set a provider key, describe what you want, and the AI designs services, writes handlers, compiles, and starts them:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY, GEMINI_API_KEY, ...
+micro run --prompt "a task management system with categories" --provider anthropic
+```
+
+The AI designs the architecture, you review it, then it generates handlers with real business logic, compiles them, and starts them:
+
+```
+Services:
+  ● task — Task management with status tracking
+  ● project — Project organization
+
+Generate? [Y/n]
+
+Micro
+  Services:
+    ● task
+    ● project
+  Agents:
+    ◆ agent
+```
+
+Then talk to your services from the console:
+
+```
+> Create a project called Launch, then add three tasks to it
+
+→ project_Project_Create({"name":"Launch"})
+← {"record":{"id":"p1..."},"success":true}
+→ task_Task_Create({"title":"Design specs","project_id":"p1..."})
+→ task_Task_Create({"title":"Write code","project_id":"p1..."})
+→ task_Task_Create({"title":"Ship it","project_id":"p1..."})
+
+Created Work category and added 'Finish report' task to it.
+```
+
+When you need a capability that doesn't exist, the agent generates a new service mid-conversation:
+
+```
+> I need to track shipping. Create a shipment for order 123 to London.
+
+  ⚡ generating shipping service...
+  ✓ shipping
+  → shipping_Shipping_Create({"order_id":"123","destination":"London"})
+  ← {"record":{"id":"xyz...","status":"pending"}}
+
+  Created shipment for order 123 going to London.
+```
+
+Edit the generated code by hand at any time — re-running preserves your changes. [Read more](https://go-micro.dev/blog/13).
+
+## Writing Services
+
+Under the hood, a service is a struct with methods. Doc comments and `@example` tags become tool descriptions for AI agents automatically.
 
 ```go
 package main
 
 import (
-        "go-micro.dev/v5"
+    "go-micro.dev/v6"
 )
 
 type Request struct {
-        Name string `json:"name"`
+    Name string `json:"name"`
 }
 
 type Response struct {
-        Message string `json:"message"`
+    Message string `json:"message"`
 }
 
 type Say struct{}
 
-func (h *Say) Hello(ctx context.Context, req *Request, rsp *Response) error {
-        rsp.Message = "Hello " + req.Name
-        return nil
-}
-
-func main() {
-        // create the service
-        service := micro.New("helloworld")
-
-        // register handler
-        service.Handle(new(Say))
-
-        // run the service
-        service.Run()
-}
-```
-
-Set a fixed address
-
-```go
-service := micro.NewService(
-    micro.Name("helloworld"),
-    micro.Address(":8080"),
-)
-```
-
-Call it via curl
-
-```bash
-curl -XPOST \
-     -H 'Content-Type: application/json' \
-     -H 'Micro-Endpoint: Say.Hello' \
-     -d '{"name": "alice"}' \
-      http://localhost:8080
-```
-
-## MCP & AI Agents
-
-Go Micro is designed for an **agent-first** workflow. Every service you build automatically becomes a tool that AI agents can discover and use via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
-
-- **[🤖 Agent Playground](https://go-micro.dev/docs/mcp.html)** — Chat with your services through an interactive AI agent at `/agent`
-- **[🔧 MCP Tools Registry](https://go-micro.dev/docs/mcp.html)** — Browse all services exposed as AI-callable tools at `/api/mcp/tools`
-- **[📖 MCP Documentation](https://go-micro.dev/docs/mcp.html)** — Full guide to MCP integration, auth, and scopes
-
-### Services as Tools
-
-Write a normal Go Micro service and it's instantly available as an MCP tool:
-
-```go
-// SayHello greets a person by name.
+// Hello greets a person by name.
 // @example {"name": "Alice"}
-func (g *GreeterService) SayHello(ctx context.Context, req *HelloRequest, rsp *HelloResponse) error {
+func (h *Say) Hello(ctx context.Context, req *Request, rsp *Response) error {
     rsp.Message = "Hello " + req.Name
     return nil
 }
+
+func main() {
+    service := micro.NewService("greeter")
+    service.Handle(new(Say))
+    service.Run()
+}
 ```
 
-Run with `micro run` and the agent playground and MCP tools registry are ready:
+Run it and everything is accessible — REST, gRPC, MCP, agent playground:
 
 ```bash
 micro run
-# Agent Playground:  http://localhost:8080/agent
-# MCP Tools:         http://localhost:8080/api/mcp/tools
+# Dashboard:   http://localhost:8080
+# API:         http://localhost:8080/api/{service}/{method}
+# Agent:       http://localhost:8080/agent
+# MCP Tools:   http://localhost:8080/mcp/tools
 ```
 
-Use `micro mcp serve` for local AI tools like Claude Code, or connect any MCP-compatible agent to the HTTP endpoint.
-
-See the [MCP guide](https://go-micro.dev/docs/mcp.html) for authentication, scopes, and advanced usage.
-
-## Examples
-
-Check out [/examples](examples/) for runnable code:
-- [hello-world](examples/hello-world/) - Basic RPC service
-- [web-service](examples/web-service/) - HTTP REST API
-- [mcp](examples/mcp/) - MCP integration with AI agents
-
-See [all examples](examples/README.md) for more.
-
-## Protobuf
-
-Install the code generator and see usage in the docs:
+You can also scaffold a service from a template:
 
 ```bash
-go install go-micro.dev/v5/cmd/protoc-gen-micro@v5.16.0
+micro new helloworld
+micro new contacts --template crud
 ```
 
-> **Note:** Use a specific version instead of `@latest` to avoid module path conflicts. See [releases](https://github.com/micro/go-micro/releases) for the latest version.
+## Building Agents
 
-Docs: [`internal/website/docs/getting-started.md`](internal/website/docs/getting-started.md)
+An Agent is a service with an LLM inside it. It has a proto-defined `Agent.Chat` RPC endpoint, registers in the registry, and is callable like any service:
 
-## Command Line
-
-Install the CLI:
-
-```
-go install go-micro.dev/v5/cmd/micro@v5.16.0
+```go
+agent := micro.NewAgent("task-mgr",
+    micro.AgentServices("task", "project"),
+    micro.AgentPrompt("You manage tasks and projects. You understand deadlines and priorities."),
+    micro.AgentProvider("anthropic"),
+)
+agent.Run()
 ```
 
-> **Note:** Use a specific version instead of `@latest` to avoid module path conflicts. See [releases](https://github.com/micro/go-micro/releases) for the latest version.
+The agent discovers its services from the registry, scopes its tools to their endpoints, and maintains conversation memory in the store. It registers itself so `micro chat` and other agents can find it.
 
-### Quick Start
+```go
+// Programmatic interaction
+resp, _ := agent.Ask(ctx, "What tasks are overdue?")
+fmt.Println(resp.Reply)
+```
+
+Multiple agents coordinate via RPC — each is a service with an `Agent.Chat` endpoint. `micro chat` routes to the right one.
 
 ```bash
-micro new helloworld   # Create a new service
-cd helloworld
-micro run              # Run with API gateway and hot reload
+micro agent list                    # list registered agents
+micro call task-mgr Agent.Chat '{"message": "What tasks are overdue?"}'
 ```
 
-Then open http://localhost:8080 to see your service and call it from the browser.
+### Plan & Delegate
 
-### Development Workflow
+Every agent gets two built-in capabilities, exposed as tools — no extra setup, no harness:
 
-| Stage | Command | Purpose |
-|-------|---------|---------|
-| **Develop** | `micro run` | Local dev with hot reload and API gateway |
-| **Build** | `micro build` | Compile production binaries |
-| **Deploy** | `micro deploy` | Push to a remote Linux server via SSH + systemd |
-| **Dashboard** | `micro server` | Optional production web UI with JWT auth |
+- **`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.
 
-### micro run
+This keeps intelligence distributed: an agent doesn't need to know *how* to do everything, only *who* does. See [examples/agent-plan-delegate](examples/agent-plan-delegate/).
 
-`micro run` starts your services with:
-- **Web Dashboard** - Browse and call services at `/`
-- **Agent Playground** - AI chat with MCP tools at `/agent`
-- **API Explorer** - Browse endpoints and schemas at `/api`
-- **API Gateway** - HTTP to RPC proxy at `/api/{service}/{method}` (no auth in dev mode)
-- **MCP Tools** - Services as AI tools at `/api/mcp/tools`
-- **Health Checks** - Aggregated health at `/health`
-- **Hot Reload** - Auto-rebuild on file changes
+```go
+// A sub-agent is just an agent — created with New, talked to with Ask.
+// delegate-first: reuse a registered agent, or spin up a focused one.
+resp, _ := agent.Ask(ctx, "Plan the launch, create the tasks, and have comms notify the owner.")
+```
 
-> **Note:** `micro run` and `micro server` use a unified gateway architecture. See [Gateway Architecture](cmd/micro/README.md#gateway-architecture) for details.
+### Batteries included, pluggable
+
+Just as a service composes pluggable abstractions (registry, broker, store), an agent composes a **model**, **memory**, and **tools** — sane defaults out of the box, each swappable.
+
+```go
+agent := micro.NewAgent("assistant",
+    micro.AgentProvider("anthropic"),                 // model — swap the provider
+    micro.AgentMemory(micro.NewInMemory(50)),         // memory — default is store-backed & durable
+    micro.AgentTool("weather", "Get the weather for a city",
+        map[string]any{"city": map[string]any{"type": "string"}},
+        func(ctx context.Context, in map[string]any) (string, error) {
+            return getWeather(in["city"].(string))    // tools beyond your services — any function
+        }),
+    micro.AgentMaxSteps(8),                            // guardrails
+)
+```
+
+**Memory** is durable and store-backed by default (Postgres, NATS KV, or file), so an agent picks up where it left off after a restart — or supply your own with `AgentMemory`. **Tools** are your services automatically, plus any function you register with `AgentTool`.
+
+### Paid tools (x402)
+
+Every endpoint is an AI-callable tool — and it can be a *paid* tool. Go Micro supports [x402](https://x402.org), the HTTP 402 payment standard for agents, so a tool can require a stablecoin payment and an agent can settle it autonomously. It's opt-in and carries no crypto in the framework: verification is delegated to a pluggable facilitator (Coinbase, Alchemy, self-hosted), so Base and Solana are just different facilitators.
 
 ```bash
-micro run                    # Gateway on :8080
-micro run --address :3000    # Custom gateway port
-micro run --no-gateway       # Services only
-micro run --env production   # Use production environment
+# Charge for tool calls at the MCP gateway (off unless you set a pay-to address)
+micro mcp serve --x402-pay-to 0xYourAddress --x402-network solana --x402-amount 10000
+# Per-tool amounts via a config file
+micro mcp serve --x402-config x402.json
 ```
 
-### Configuration
+See the [Payments (x402) guide](internal/website/docs/guides/x402-payments.md).
 
-For multi-service projects, create a `micro.mu` file:
+### Reachable by other agents (A2A)
+
+Within a Go Micro system, agents reach each other over RPC. To make them reachable by agents on *other* frameworks, Go Micro speaks the [Agent2Agent (A2A) protocol](https://a2a-protocol.org). The A2A gateway discovers your agents from the registry, generates an Agent Card for each from its metadata — the same way the MCP gateway derives tools from service endpoints — and translates incoming A2A tasks to the agent's `Agent.Chat` RPC. No per-agent code: register an agent and it's reachable over A2A.
+
+```bash
+micro a2a serve --address :4000    # gateway: expose every registered agent over A2A
+micro a2a list                     # agents and their Agent Card URLs
+```
+
+Or skip the gateway entirely — an agent can serve its own A2A endpoint directly, handling tasks in-process:
+
+```go
+micro.NewAgent("task-mgr", micro.AgentServices("task"), micro.AgentA2A(":4000"))
+```
+
+It works both ways. To call an agent on another framework, an `a2a.Client` is wired into the two places that hand off work: `flow.A2A(url)` as a workflow step (the cross-framework `Dispatch`), and `delegate` to an `http(s)` URL from inside an agent.
+
+MCP exposes your services as tools; A2A exposes your agents as agents. See the [A2A guide](internal/website/docs/guides/a2a-protocol.md).
+
+## Features
+
+### AI
+
+| Feature | Details |
+|---------|---------|
+| Agents | `micro.NewAgent()` — intelligent layer that manages services |
+| Plan & delegate | Built-in agent tools — plan multi-step work, delegate subtasks to other agents |
+| Pluggable memory | Durable store-backed conversation memory by default; swap with `AgentMemory` |
+| Custom tools | `AgentTool` — give an agent any function as a tool, beyond its services |
+| Guardrails | `MaxSteps` (stop on count), `LoopLimit` (stop repeated no-progress calls), `ApproveTool` (human-in-the-loop) |
+| Tool middleware | `AgentWrapTool` — wrap tool execution for logging, metrics, or retries (like client/server wrappers) |
+| Workflows | `micro.NewFlow()` — event-driven; one step, ordered durable steps, or triggers an agent |
+| Durable execution | Checkpointed flow steps survive a crash and resume where they stopped; store-backed by default, pluggable backend |
+| MCP gateway | Every endpoint is an AI tool automatically |
+| A2A gateway | Every agent is reachable over the Agent2Agent protocol; cards generated from the registry (`micro a2a`) |
+| Payments (x402) | Opt-in per-call payments for tools via the x402 standard; pluggable facilitator (Base, Solana, …) |
+| 7 LLM providers | Anthropic, OpenAI, Gemini, Groq, Mistral, Together, Atlas Cloud |
+| Interactive console | `micro run` includes a chat console for talking to services |
+| Service generation | `micro run --prompt` — describe a system, get running services |
+
+### Framework
+
+| Feature | Details |
+|---------|---------|
+| Service registry | mDNS (default), Consul, etcd |
+| RPC client/server | gRPC transport, load balancing, streaming |
+| Pub/sub events | NATS, RabbitMQ, HTTP broker |
+| Key-value store | File (bbolt), Postgres, NATS KV |
+| Typed model layer | CRUD + queries, SQLite/Postgres backends |
+| Everything swappable | All abstractions are Go interfaces |
+
+### Developer experience & deployment
+
+| Feature | Details |
+|---------|---------|
+| Hot reload | `micro run` watches files, rebuilds on change |
+| Templates | `micro new --template crud/pubsub/api` |
+| One-command deploy | `micro deploy user@server` — SSH + systemd, no Docker |
+
+## CLI
+
+| Command | Purpose |
+|---------|---------|
+| `micro run --prompt "..."` | Generate services + agent, start with interactive console |
+| `micro run` | Dev mode: hot reload, gateway, interactive console |
+| `micro run -d` | Detached mode (no console) |
+| `micro chat` | Standalone chat (when not using micro run) |
+| `micro agent list` | List registered agents |
+| `micro new myservice` | Scaffold a service |
+| `micro call service endpoint '{}'` | Call a service or agent from the CLI |
+| `micro build` | Compile production binaries |
+| `micro deploy user@server` | Deploy via SSH + systemd |
+
+## Multi-Service Projects
+
+Run multiple services together:
+
+```go
+users := micro.NewService("users", micro.Address(":9001"))
+orders := micro.NewService("orders", micro.Address(":9002"))
+
+users.Handle(new(Users))
+orders.Handle(new(Orders))
+
+g := micro.NewGroup(users, orders)
+g.Run()
+```
+
+Or use a `micro.mu` config file:
 
 ```
 service users
     path ./users
-    port 8081
 
-service posts
-    path ./posts
-    port 8082
+service orders
+    path ./orders
     depends users
-
-env development
-    DATABASE_URL sqlite://./dev.db
 ```
 
-The gateway runs on :8080 by default, so services should use other ports.
+## Data Model
 
-### Deployment
+Typed persistence with CRUD and queries:
 
-Deploy to any Linux server with systemd:
+```go
+type User struct {
+    ID    string `json:"id" model:"key"`
+    Name  string `json:"name"`
+    Email string `json:"email" model:"index"`
+}
 
-```bash
-# On your server (one-time setup)
-curl -fsSL https://go-micro.dev/install.sh | sh
-sudo micro init --server
+db := service.Model()
+db.Register(&User{})
+db.Create(ctx, &User{ID: "1", Name: "Alice", Email: "alice@example.com"})
 
-# From your laptop
-micro deploy user@your-server
+var results []*User
+db.List(ctx, &results, model.Where("email", "alice@example.com"))
 ```
 
-The deploy command:
-1. Builds binaries for Linux
-2. Copies via SSH to the server
-3. Sets up systemd services
-4. Verifies services are healthy
+Backends: memory (default), SQLite, Postgres.
 
-Optionally run `micro server` on the deployed machine for a production web dashboard with JWT auth, user management, and API explorer.
+## AI Providers
 
-Manage deployed services:
-```bash
-micro status --remote user@server    # Check status
-micro logs --remote user@server      # View logs
-micro logs myservice --remote user@server -f  # Follow specific service
+Swap providers with a single import — same interface everywhere:
+
+| Provider | Default Model |
+|----------|---------------|
+| Anthropic | `claude-sonnet-4-20250514` |
+| OpenAI | `gpt-4o` |
+| Google Gemini | `gemini-2.5-flash` |
+| Groq | `llama-3.3-70b-versatile` |
+| Mistral | `mistral-large-latest` |
+| Together AI | `Llama-3.3-70B-Instruct-Turbo` |
+| Atlas Cloud | `llama-3.3-70b` |
+
+```go
+m := ai.New("anthropic", ai.WithAPIKey(key))
+resp, _ := m.Generate(ctx, &ai.Request{Prompt: "hello"})
 ```
 
-No Docker required. No Kubernetes. Just systemd.
+## Examples
 
-See [internal/website/docs/deployment.md](internal/website/docs/deployment.md) for full deployment guide.
+- [hello-world](examples/hello-world/) — Basic RPC service
+- [multi-service](examples/multi-service/) — Multiple services in one binary
+- [mcp](examples/mcp/) — MCP integration with AI agents
+- [agent-plan-delegate](examples/agent-plan-delegate/) — Agent planning and multi-agent delegation
+- [grpc-interop](examples/grpc-interop/) — Call go-micro from any gRPC client
 
-See [cmd/micro/README.md](cmd/micro/README.md) for full CLI documentation.
+See [all examples](examples/README.md).
 
-Docs: [`internal/website/docs`](internal/website/docs)
+## Docs
 
-Package reference: https://pkg.go.dev/go-micro.dev/v5
-
-**User Guides:**
 - [Getting Started](internal/website/docs/getting-started.md)
+- [AI Integration](internal/website/docs/ai-integration.md)
+- [Agents and Workflows](internal/website/docs/guides/agents-and-workflows.md)
+- [Agent Design](internal/docs/AGENT_DESIGN.md)
+- [Plan & Delegate](internal/website/docs/guides/plan-delegate.md)
+- [Agent Guardrails](internal/website/docs/guides/agent-guardrails.md)
+- [Payments (x402)](internal/website/docs/guides/x402-payments.md)
 - [MCP & AI Agents](internal/website/docs/mcp.md)
-- [Plugins Overview](internal/website/docs/plugins.md)
-- [Learn by Example](internal/website/docs/examples/index.md)
-- [Deployment Guide](internal/website/docs/deployment.md)
+- [Data Model](internal/website/docs/model.md)
+- [Deployment](internal/website/docs/deployment.md)
+- [Plugins](internal/website/docs/plugins.md)
 
-**Architecture & Performance:**
-- [Performance Considerations](internal/website/docs/performance.md)
-- [Reflection Usage & Philosophy](internal/website/docs/REFLECTION-EVALUATION-SUMMARY.md)
-
-**Security:**
-- [TLS Security Migration](internal/website/docs/TLS_SECURITY_UPDATE.md)
-- [Security Migration Guide](internal/website/docs/SECURITY_MIGRATION.md)
-
-## Adopters
-
-- [Sourse](https://sourse.eu) - Work in the field of earth observation, including embedded Kubernetes running onboard aircraft, and we’ve built a mission management SaaS platform using Go Micro.
+Package reference: https://pkg.go.dev/go-micro.dev/v6

ROADMAP.md

@@ -1,165 +1,75 @@
 # Go Micro Roadmap
 
-This roadmap outlines the planned features and improvements for Go Micro. Community feedback and contributions are welcome!
+Go Micro is a framework for building **agents and services** in Go. An agent is a
+distributed system — it discovers services, calls them, holds state, and recovers
+from failure — so building an agent is building a service. The roadmap has two
+jobs: make **agentic development** excellent, and make the **developer experience**
+around it excellent.
 
-> **🚀 NEW:** See [ROADMAP_2026.md](ROADMAP_2026.md) for the **AI-Native Era roadmap** focused on MCP integration, agent-first development, and business sustainability. This document covers general framework improvements.
+The full, current roadmap lives at **[go-micro.dev/docs/roadmap](https://go-micro.dev/docs/roadmap)**
+([source](internal/website/docs/roadmap.md)). The highlights:
 
-## Current Focus (Q1 2026)
+## Where we are (v6)
 
-### Documentation & Developer Experience
-- [x] Modernize documentation structure
-- [x] Add learn-by-example guides
-- [x] Update issue templates
-- [ ] Create video tutorials
-- [ ] Interactive documentation site
-- [ ] Plugin discovery dashboard
+Services, agents (`plan`/`delegate`, guardrails, memory, tool middleware), durable
+flows, the MCP and A2A gateways (both directions), x402 paid tools, secure by
+default.
 
-### Observability
-- [ ] OpenTelemetry native support
-- [ ] Auto-instrumentation for handlers
-- [ ] Metrics export standardization
-- [ ] Distributed tracing examples
-- [ ] Integration with popular observability platforms
+## Principles
 
-### Developer Tools
-- [ ] `micro dev` with hot reload
-- [ ] Service templates (`micro new --template`)
-- [ ] Better error messages with suggestions
-- [ ] Debug tooling improvements
-- [ ] VS Code extension for Go Micro
+1. Build into what people run, never a separate product (no hosted platform, no
+   enterprise edition, no VC).
+2. CLI-first — the CLI is the experience; UI must earn its place, never bloat.
+3. The getting-started flow is a contract: *0→1* (scaffold → run → call) and
+   *0→hero* (a working multi-agent system) must always work and are verified on
+   every change.
+4. Interaction matters as much as running — chatting with agents, inspecting runs
+   and history, end to end.
+5. Battle-tested: works across every provider, fails safely, observable.
 
-## Q2 2026
+## Now — hardening
 
-### Production Readiness
-- [ ] Health check standardization
-- [ ] Graceful shutdown improvements
-- [ ] Resource cleanup best practices
-- [ ] Load testing framework integration
-- [ ] Performance benchmarking suite
+- **Cross-provider conformance** — the same agent scenario across all seven
+  providers, gated on keys, on a schedule.
+- **Failure & resilience** — timeouts, rate limits, cancellation, deadline/context
+  propagation, retry/backoff.
+- **Getting-started contract** — define and CI-verify the 0→1 and 0→hero flows.
 
-### Cloud Native
-- [ ] Kubernetes operator
-- [ ] Helm charts for common setups
-- [ ] Service mesh integration guides (Istio, Linkerd)
-- [ ] Cloud provider quickstarts (AWS, GCP, Azure)
-- [ ] Multi-cluster patterns
+## Next — agentic depth
 
-### Security
-- [ ] mTLS by default option
-- [ ] Secret management integration (Vault, AWS Secrets Manager)
-- [ ] RBAC improvements
-- [ ] Security audit and hardening
-- [ ] CVE scanning and response process
+- **Durable agent loop** — resume a long run via `Checkpoint` (flows already do).
+- **Streaming** — `ai.Stream` + A2A `message/stream`, end to end.
+- **Agent observability** — `RunInfo` → OpenTelemetry spans.
 
-## Q3 2026
+## Later
 
-### Plugin Ecosystem
-- [ ] Plugin marketplace/registry
-- [ ] Plugin quality standards
-- [ ] Community plugin contributions
-- [ ] Plugin compatibility matrix
-- [ ] Auto-discovery of available plugins
+- Memory management (summarization, retrieval/RAG); human-in-the-loop pause/resume;
+  x402 live-facilitator conformance and paid remote tools with spend caps; A2A
+  streaming, push notifications, and multi-turn tasks.
 
-### Streaming & Async
-- [ ] Improved streaming support
-- [ ] Server-sent events (SSE) support
-- [ ] WebSocket plugin
-- [ ] Event sourcing patterns
-- [ ] CQRS examples
+## Developer experience (ongoing)
 
-### Testing
-- [ ] Mock generation tooling
-- [ ] Integration test helpers
-- [ ] Contract testing support
-- [ ] Chaos engineering examples
-- [ ] E2E testing framework
+- A seamless CLI inner loop (scaffold → run → chat → inspect → deploy); UI
+  discipline (trim what isn't great); a maintained real-world example that doubles
+  as the 0→hero reference; docs kept in lockstep with the code.
 
-## Q4 2026
+## How it's sustained
 
-### Performance
-- [ ] Connection pooling optimizations
-- [ ] Zero-allocation paths
-- [ ] gRPC performance improvements
-- [ ] Caching strategies guide
-- [ ] Performance profiling tools
+The framework is the product, funded by sponsorship from those who run it — not a
+hosted service, enterprise tier, or venture funding. See
+[the v6 story](https://go-micro.dev/blog/27).
 
-### Developer Productivity
-- [ ] Code generation improvements
-- [ ] Better IDE support
-- [ ] Debugging tools
-- [ ] Migration automation tools
-- [ ] Upgrade helpers
+## Contributing & feedback
 
-### Community
-- [ ] Regular blog posts and case studies
-- [ ] Community spotlight program
-- [ ] Contribution rewards
-- [ ] Monthly community calls
-- [ ] Conference presence
+Pick an item, open an issue to discuss the approach, and submit a PR. Or join the
+[Discord](https://discord.gg/WeMU5AGxD). Include tests, run `make test` and
+`make lint`.
 
-## Long-term Vision
+## Version support
 
-### Core Framework
-- Maintain backward compatibility (Go Micro v5+)
-- Progressive disclosure of complexity
-- Best-in-class developer experience
-- Production-grade reliability
-- Comprehensive plugin ecosystem
+- **v6** — active development (current).
+- **v5** — security fixes only.
+- **v4 and earlier** — end of life.
 
-### Ecosystem Goals
-- 100+ production deployments documented
-- 50+ community plugins
-- Active contributor community
-- Regular releases (monthly patches, quarterly features)
-- Comprehensive benchmarks vs alternatives
-
-### Differentiation
-- **Batteries included, fully swappable** - Start simple, scale complex
-- **Zero-config local development** - No infrastructure required to start
-- **Plugin ecosystem in-repo** - No version compatibility hell
-- **Progressive complexity** - Learn as you grow
-- **Cloud-native first** - Built for Kubernetes and containers
-
-## Contributing
-
-We welcome contributions to any roadmap items! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-### High Priority Areas
-1. Documentation improvements
-2. Real-world examples
-3. Plugin development
-4. Performance optimizations
-5. Testing infrastructure
-
-### How to Contribute
-- Pick an item from the roadmap
-- Open an issue to discuss approach
-- Submit a PR with implementation
-- Help review others' contributions
-
-## Feedback
-
-Have suggestions for the roadmap? 
-
-- Open a [feature request](.github/ISSUE_TEMPLATE/feature_request.md)
-- Start a discussion in GitHub Discussions
-- Comment on existing roadmap issues
-
-## Version Compatibility
-
-We follow semantic versioning:
-- Major versions (v5 → v6): Breaking changes
-- Minor versions (v5.3 → v5.4): New features, backward compatible
-- Patch versions (v5.3.0 → v5.3.1): Bug fixes, no API changes
-
-## Support Timeline
-
-- v5: Active development (current)
-- v4: Security fixes only (until v6 release)
-- v3: End of life
-
----
-
-Last updated: November 2025
-
-This roadmap is subject to change based on community needs and priorities. Star the repo to stay updated! ⭐
+Major versions (v5 → v6) carry breaking changes; minors are backward-compatible.
+See the [v5 → v6 migration guide](https://go-micro.dev/docs/guides/migration/v5-to-v6).

ROADMAP_2026.md

@@ -1,954 +0,0 @@
-# Go Micro Roadmap 2026: The AI-Native Era
-
-**Last Updated:** February 2026
-
-## Executive Summary
-
-The emergence of AI agents represents a **paradigm shift** in how services are consumed. Where APIs served apps, **MCP serves agents**. Go Micro is uniquely positioned to become the **standard microservices framework for the agent era**.
-
-This roadmap outlines Go Micro's evolution from an API-first framework to an **AI-native platform** while maintaining backward compatibility and ensuring long-term sustainability.
-
----
-
-## The Paradigm Shift
-
-### Before: Apps → API Gateway → Services
-```
-┌──────────┐     HTTP/REST      ┌─────────────┐     RPC      ┌──────────┐
-│  Mobile  │ ───────────────→   │   Gateway   │ ─────────→   │ Services │
-│   App    │                    │  (Express)  │              │          │
-└──────────┘                    └─────────────┘              └──────────┘
-```
-
-Characteristics:
-- Apps need HTTP/REST/GraphQL
-- Manual API design (OpenAPI specs)
-- Developers write integration code
-- Static endpoint documentation
-
-### Now: Agents → MCP → Services
-```
-┌──────────┐      MCP/SSE       ┌─────────────┐     RPC      ┌──────────┐
-│  Claude  │ ───────────────→   │     MCP     │ ─────────→   │ Services │
-│   GPT    │                    │   Gateway   │              │          │
-└──────────┘                    └─────────────┘              └──────────┘
-```
-
-Characteristics:
-- Agents discover tools automatically
-- No manual API design needed
-- Agents write their own integration code
-- Dynamic tool discovery
-
-### Why This Matters
-
-**API Gateways solve integration for developers.**
-**MCP solves integration for AI.**
-
-Go Micro's MCP integration means:
-1. **Zero integration work** - Services become AI-accessible instantly
-2. **No API wrappers** - Agents call services directly
-3. **Dynamic discovery** - New services = new tools automatically
-4. **Natural language interface** - No documentation needed
-
----
-
-## Strategic Vision
-
-### Mission Statement
-
-> **Make every microservice AI-native by default.**
-
-### 2026-2027 Goals
-
-1. **MCP becomes the default** - `micro run` enables MCP automatically
-2. **Best-in-class agent integration** - The easiest way to expose services to AI
-3. **Sustainable business model** - Open core with premium offerings
-4. **Production deployment at scale** - 1000+ services running MCP gateways
-5. **Ecosystem leadership** - The go-to framework when AI needs microservices
-
----
-
-## Roadmap
-
-## Q1 2026: MCP Foundation ✅ COMPLETE
-
-**Status:** COMPLETE as of February 2026
-
-### Delivered
-- [x] MCP library (`gateway/mcp`)
-- [x] CLI integration (`micro run --mcp-address`)
-- [x] Service discovery and tool generation
-- [x] HTTP/SSE transport
-- [x] Documentation and examples
-- [x] Blog post and launch
-
-### Impact
-- Services are now AI-accessible with 3 lines of code
-- Both library and CLI users can use MCP
-- Foundation for agent-first development
-
----
-
-## Q2 2026: Agent Developer Experience
-
-**Status:** IN PROGRESS - Several features delivered early (Feb 2026)
-
-**Theme:** Make it trivial for any AI to call your services
-
-### MCP Enhancements
-
-#### Stdio Transport for Claude Code ✅ COMPLETE (delivered early)
-- [x] Implement stdio JSON-RPC protocol
-- [x] Auto-detection: stdio vs HTTP based on environment
-- [x] `micro mcp` command for Claude Code integration
-- [x] Example: Add go-micro services to Claude Code
-
-**Why:** Claude Code and other local AI tools use stdio MCP servers. This enables:
-```bash
-# In Claude Code config
-{
-  "mcpServers": {
-    "my-services": {
-      "command": "micro",
-      "args": ["mcp"]
-    }
-  }
-}
-```
-
-**Business value:** Direct integration with Anthropic's flagship developer tool.
-
-#### Tool Descriptions from Comments ✅ COMPLETE (delivered early)
-- [x] Parse Go comments to generate tool descriptions
-- [x] Support JSDoc-style tags: `@param`, `@return`, `@example`
-- [x] Schema generation from struct tags
-- [ ] Auto-generate examples from test cases
-
-**Before:**
-```
-Tools:
-- users.Users.Get - Call Get on users service
-```
-
-**After:**
-```
-Tools:
-- users.Users.Get
-  Description: Retrieve user profile by ID. Returns full profile including email,
-               name, created date, and preferences.
-  Parameters:
-    - id (string, required): User ID in UUID format
-  Returns: User object with profile fields
-  Example: {"id": "123e4567-e89b-12d3-a456-426614174000"}
-```
-
-**Why:** Better descriptions = better agent performance. Agents need context to call services correctly.
-
-#### Multi-Protocol Support
-- [ ] WebSocket transport for streaming
-- [ ] gRPC reflection for MCP (bidirectional streaming)
-- [x] Server-Sent Events with auth (HTTP/SSE implemented)
-- [ ] HTTP/3 support
-
-**Why:** Different agents prefer different protocols. Support them all.
-
-### Agent SDKs
-
-Create official SDKs for popular agent frameworks:
-
-#### LangChain Integration
-- [ ] `go-micro-langchain` package
-- [ ] Auto-generate LangChain tools from registry
-- [ ] Example: Multi-agent workflow with go-micro services
-
-#### LlamaIndex Integration
-- [ ] `go-micro-llamaindex` package
-- [ ] Service discovery as data sources
-- [ ] Example: RAG with microservices
-
-#### AutoGPT/AgentGPT Support
-- [ ] Plugin format adapter
-- [ ] Auto-install via plugin marketplace
-- [ ] Example: Autonomous agents orchestrating services
-
-**Business value:** Every agent framework can use go-micro services out of the box.
-
-### Developer Experience
-
-#### `micro mcp` Command Suite ✅ PARTIALLY COMPLETE
-
-**Implemented:**
-```bash
-# Start MCP server
-micro mcp serve                    # Stdio (for Claude Code) ✅
-micro mcp serve --address :3000    # HTTP/SSE (for web agents) ✅
-
-# Development
-micro mcp list                     # List available tools ✅
-micro mcp list --json              # JSON output ✅
-```
-
-**Not Yet Implemented:**
-```bash
-micro mcp test users.Users.Get     # Test a tool (placeholder only)
-micro mcp docs                     # Generate MCP documentation
-micro mcp export langchain         # Export to LangChain format
-micro mcp export openapi           # Export as OpenAPI (for fallback)
-```
-
-#### Interactive Agent Playground
-- [ ] Web UI for testing services with AI
-- [ ] Built into `micro run` dashboard
-- [ ] Chat with your services
-- [ ] See agent tool calls in real-time
-- [ ] Share playground URLs for demos
-
-**Example:**
-```
-http://localhost:8080/playground
-
-> You: "Show me user 123's last 5 orders"
-
-Agent: Let me check that...
-→ Calling users.Users.Get with {"id": "123"}
-→ Calling orders.Orders.List with {"user_id": "123", "limit": 5}
-
-Here are the 5 most recent orders for Alice Smith:
-1. Order #45678 - $125.00 - Shipped (Jan 15)
-2. Order #45123 - $89.99 - Delivered (Jan 10)
-...
-```
-
-**Business value:** Instant demos. Show investors/customers AI calling your services.
-
-### Documentation
-
-- [ ] "Building AI-Native Services" guide
-- [ ] Agent integration patterns
-- [ ] Best practices for tool descriptions
-- [ ] MCP security guide
-- [ ] Video: "Your First AI-Native Service in 5 Minutes"
-
----
-
-## Q3 2026: Production & Scale
-
-**Status:** IN PROGRESS - Core security features delivered early (Feb 2026)
-
-**Theme:** Run MCP gateways in production at scale
-
-### Enterprise MCP Gateway
-
-Create a production-grade standalone MCP gateway:
-
-#### Gateway Features
-- [ ] Standalone binary: `micro-mcp-gateway`
-- [ ] Horizontal scaling (stateless design)
-- [x] Rate limiting per agent/token ✅ (delivered early)
-- [ ] Usage tracking and analytics
-- [x] Cost attribution (track which agent called what) ✅ (audit logging)
-- [ ] Circuit breakers for service protection
-- [ ] Request/response caching
-- [ ] Multi-tenant support (isolate services by namespace)
-
-**Deployment:**
-```bash
-# Standalone gateway
-micro-mcp-gateway \
-  --registry consul:8500 \
-  --address :3000 \
-  --auth jwt \
-  --rate-limit 1000/hour \
-  --cache redis:6379
-```
-
-**Business value:** Enterprise customers need production-grade MCP gateways. This is a **paid offering**.
-
-#### Observability
-- [ ] OpenTelemetry integration
-- [x] Agent call tracing (which agent called what) ✅ (trace IDs implemented)
-- [ ] Tool usage metrics (which tools are popular)
-- [ ] Performance dashboards
-- [ ] Anomaly detection (unusual agent behavior)
-- [ ] Cost analysis (cloud spend per agent)
-
-**Dashboard Example:**
-```
-Agent Activity - Last 7 Days
-─────────────────────────────
-Claude Desktop    1,234 calls   $12.34 compute cost
-ChatGPT Plugin    567 calls     $5.67 compute cost
-Custom Agent      234 calls     $2.34 compute cost
-
-Top Services
-────────────
-users    45%
-orders   30%
-payments 15%
-
-Slowest Tools
-─────────────
-analytics.Reports.Generate   2.3s avg
-payments.Payments.Process    890ms avg
-```
-
-**Business value:** Enterprises need observability. This justifies MCP Gateway pricing.
-
-### Security ✅ CORE FEATURES COMPLETE (delivered early)
-
-#### Agent Authentication ✅ COMPLETE
-- [x] Auth provider integration (auth.Auth)
-- [x] Bearer token authentication
-- [x] Scope-based permissions (agent can only call certain services)
-- [x] Audit logging (full trail of what agents accessed)
-- [ ] OAuth2 for agent authorization (basic auth implemented)
-- [ ] API keys per agent (bearer tokens supported)
-
-**Implemented Example:**
-```go
-mcp.Serve(mcp.Options{
-    Registry: registry,
-    Auth:     authProvider,  // ✅ Implemented
-    Scopes: map[string][]string{  // ✅ Implemented
-        "blog.Blog.Create": {"blog:write"},
-        "blog.Blog.Delete": {"blog:admin"},
-    },
-    AuditFunc: func(r mcp.AuditRecord) {  // ✅ Implemented
-        log.Printf("[audit] %+v", r)
-    },
-})
-```
-
-#### Service-Side Authorization ✅ COMPLETE
-- [x] Services can validate which agent is calling
-- [x] Agent identity in context (via metadata)
-- [x] Fine-grained permissions (Agent X can read but not write)
-- [x] Trace ID propagation for debugging
-
-**Implemented - Metadata in Context:**
-```go
-// Trace ID, Tool Name, and Account ID are automatically
-// propagated to services via context metadata:
-// - Mcp-Trace-Id
-// - Mcp-Tool-Name  
-// - Mcp-Account-Id
-```
-
-**Future Enhancement - Service-Side Example:**
-```go
-// Future: Direct access to agent info from context
-func (s *Users) Delete(ctx context.Context, req *Request, rsp *Response) error {
-    // For now, services can read metadata keys:
-    // Mcp-Account-Id, Mcp-Trace-Id, Mcp-Tool-Name
-    md, _ := metadata.FromContext(ctx)
-    accountID := md["Mcp-Account-Id"]
-    
-    if accountID != "admin-account" {
-        return errors.Forbidden("users", "admin only")
-    }
-    // ...
-}
-```
-
-**Business value:** Security is a hard requirement for enterprise adoption.
-
-### Deployment Patterns
-
-#### Kubernetes Operator
-- [ ] `micro-operator` for Kubernetes
-- [ ] CRD: `MCPGateway` resource
-- [ ] Auto-scaling based on agent traffic
-- [ ] Service mesh integration
-
-**Example:**
-```yaml
-apiVersion: micro.dev/v1
-kind: MCPGateway
-metadata:
-  name: production-gateway
-spec:
-  registry: consul
-  replicas: 3
-  rateLimit:
-    perAgent: 1000/hour
-  observability:
-    otel: true
-    traces: jaeger:14268
-```
-
-#### Helm Charts
-- [ ] Official Helm chart for MCP gateway
-- [ ] Support for major registries (Consul, etcd, Kubernetes)
-- [ ] Ingress/service mesh configuration
-- [ ] Secrets management
-
-**Business value:** Easy deployment = faster adoption.
-
-### Performance
-- [ ] Connection pooling for high-throughput
-- [ ] Response streaming for long-running tools
-- [ ] Parallel tool execution when agents make multiple calls
-- [ ] Caching layer for idempotent operations
-
-**Target:** Support 10,000 concurrent agent requests on a single gateway.
-
----
-
-## Q4 2026: Ecosystem & Monetization
-
-**Theme:** Build the MCP ecosystem and sustainable business
-
-### Agent Marketplace
-
-Create a marketplace of pre-built AI agents that use go-micro services:
-
-#### Concept
-Developers build agents that solve specific problems using microservices:
-
-**Examples:**
-- **Customer Support Agent** - Integrates with users, tickets, orders services
-- **DevOps Agent** - Integrates with logs, metrics, deployments services
-- **Sales Agent** - Integrates with CRM, leads, analytics services
-- **Data Analyst Agent** - Integrates with analytics, reports services
-
-**Format:**
-```yaml
-# agent.yaml
-name: customer-support
-description: AI agent that handles customer support tickets
-services:
-  - users
-  - tickets
-  - orders
-  - payments
-prompts:
-  - system: "You are a helpful customer support agent..."
-  - examples: [...]
-mcp:
-  gateway: "mcp://services.company.com"
-pricing: free|paid
-```
-
-**Usage:**
-```bash
-# Install agent from marketplace
-micro agent install customer-support
-
-# Run agent
-micro agent run customer-support
-
-# Agent now has access to your services via MCP
-```
-
-**Business value:**
-- Marketplace fee (15% of paid agents)
-- Showcase go-micro capabilities
-- Drive framework adoption
-
-### Premium Offerings
-
-Build a sustainable business model around open-source core:
-
-#### Open Source (Free Forever)
-- Core framework (`go-micro.dev/v5`)
-- Basic MCP gateway (`gateway/mcp`)
-- CLI (`micro run`, `micro server`)
-- Documentation and examples
-- Community support
-
-#### Go Micro Cloud (SaaS)
-**Target:** Teams that want managed MCP gateways
-
-**Features:**
-- Managed MCP gateway (no ops required)
-- Built-in observability dashboard
-- Agent usage analytics
-- Multi-region deployment
-- 99.9% SLA
-- Priority support
-
-**Pricing:**
-- Starter: $99/month (10,000 agent calls/month)
-- Team: $499/month (100,000 calls/month)
-- Enterprise: Custom (millions of calls/month)
-
-**Value proposition:** "Don't run your own MCP gateway. We'll do it for you."
-
-#### Go Micro Enterprise
-**Target:** Large companies deploying at scale
-
-**Features:**
-- On-premise MCP gateway
-- SSO integration
-- Advanced security (mTLS, Vault integration)
-- Custom SLAs
-- Dedicated support
-- Training and consulting
-
-**Pricing:**
-- Starting at $10,000/year
-- Per-seat licensing or infrastructure-based
-
-**Value proposition:** "Production-grade MCP for your entire organization."
-
-#### Professional Services
-- Custom agent development
-- Migration from other frameworks
-- Architecture consulting
-- Training workshops
-- Proof-of-concept projects
-
-**Pricing:** $200-300/hour
-
-### Strategic Integrations
-
-#### Anthropic Partnership
-- [ ] Official Anthropic integration guide
-- [ ] Listed on MCP servers directory
-- [ ] Co-marketing blog posts
-- [ ] Featured in Claude documentation
-- [ ] Joint conference talks
-
-**Why:** Anthropic created MCP. Being their preferred microservices framework drives adoption.
-
-#### OpenAI Integration
-- [ ] ChatGPT plugin format support
-- [ ] GPTs integration (services as GPT actions)
-- [ ] OpenAI Assistants API support
-- [ ] Listed in OpenAI plugin store
-
-**Why:** OpenAI has largest AI user base. Tap into that market.
-
-#### Google Gemini
-- [ ] Gemini API function calling support
-- [ ] Google Cloud integration guide
-- [ ] Vertex AI compatibility
-
-#### Microsoft Copilot
-- [ ] Copilot Studio integration
-- [ ] Azure OpenAI compatibility
-- [ ] Teams bot support
-
-**Business value:** Every major AI platform can use go-micro services.
-
-### Community Growth
-
-#### Content Strategy
-- [ ] Monthly blog posts (case studies, tutorials)
-- [ ] Weekly Twitter/LinkedIn updates
-- [ ] YouTube channel (tutorials, demos)
-- [ ] Podcast: "Agents & Services" (interview users)
-
-#### Events
-- [ ] "AI-Native Microservices" conference (virtual)
-- [ ] Monthly community calls
-- [ ] Hackathons with prizes
-- [ ] Sponsor AI/agent conferences
-
-#### Open Source Program
-- [ ] Contributor rewards (swag, recognition)
-- [ ] "Agent of the Month" showcase
-- [ ] Grant program for open-source agents
-- [ ] University partnerships (courses using go-micro)
-
-**Target:** Grow from 5K GitHub stars to 15K+ by end of 2026.
-
----
-
-## 2027: Platform Dominance
-
-**Theme:** The AI-native microservices platform
-
-### Vision: The Agent Operating System
-
-Go Micro becomes the **platform layer between AI and infrastructure**:
-
-```
-┌─────────────────────────────────────┐
-│         AI Agents Layer              │
-│  Claude | GPT | Gemini | Custom     │
-└─────────────────────────────────────┘
-                 ↓ MCP
-┌─────────────────────────────────────┐
-│       Go Micro Platform              │
-│  Gateway | Registry | Auth | Mesh   │
-└─────────────────────────────────────┘
-                 ↓ RPC
-┌─────────────────────────────────────┐
-│      Microservices Layer             │
-│  Users | Orders | Payments | ...    │
-└─────────────────────────────────────┘
-```
-
-### Features
-
-#### Autonomous Service Discovery
-- Agents discover services automatically
-- AI-generated service integration code
-- Self-healing service mesh
-- Zero-config multi-cloud
-
-#### Agent Orchestration
-- Multi-agent workflows built-in
-- Agent-to-agent communication via MCP
-- Conflict resolution when agents disagree
-- Collaborative agents working on tasks
-
-#### Intelligent Routing
-- ML-based service routing (predict best endpoint)
-- A/B testing for agents
-- Canary deployments driven by agent feedback
-- Auto-scaling based on agent behavior
-
-#### Development Copilot
-- AI assistant for service development
-- Auto-generate services from requirements
-- Suggest optimizations
-- Detect bugs before deployment
-
-**Example:**
-```bash
-$ micro generate "a user authentication service with JWT"
-
-[AI] Analyzing requirements...
-[AI] Generating service scaffold...
-[AI] Adding JWT auth with RS256...
-[AI] Creating database schema...
-[AI] Writing tests...
-[AI] Service ready: ./auth-service
-
-$ cd auth-service && micro run
-[AI] Service running. MCP-enabled. Try asking Claude to create a user!
-```
-
----
-
-## Business Model Deep Dive
-
-### Revenue Streams
-
-#### 1. Go Micro Cloud (SaaS) - Primary Revenue
-**Target ARR:** $1M Year 1, $5M Year 2
-
-**Customer Segments:**
-- **Startups:** Need MCP but don't want to run infrastructure
-- **Mid-size companies:** Building AI features, need reliable MCP gateway
-- **Enterprises:** Multi-region, high-availability requirements
-
-**Unit Economics:**
-- CAC (Customer Acquisition Cost): $500 (content marketing, freemium)
-- LTV (Lifetime Value): $12,000 (2-year retention, $500/mo avg)
-- LTV:CAC ratio: 24:1 (excellent)
-
-**Growth Strategy:**
-- Freemium model (free tier up to 1,000 calls/month)
-- Self-service signup
-- Upsell to Team/Enterprise based on usage
-
-#### 2. Enterprise Licenses - High Margin
-**Target ARR:** $500K Year 1, $3M Year 2
-
-**Value Proposition:**
-- On-premise deployment
-- Enterprise support
-- Custom SLAs
-- Training included
-
-**Typical Deal:**
-- $25K-100K/year per company
-- 10-20 deals/year = $500K-$2M
-
-#### 3. Professional Services - Consulting
-**Target Revenue:** $250K Year 1, $750K Year 2
-
-**Services:**
-- Agent development (build custom agents)
-- Migration consulting (move to go-micro)
-- Architecture design
-- Training workshops
-
-**Pricing:**
-- $200-300/hour
-- 1,000-2,500 billable hours/year
-
-#### 4. Marketplace - Platform Revenue
-**Target Revenue:** $100K Year 1, $500K Year 2
-
-**Model:**
-- Take 15% of paid agent sales
-- Host agents for free (community)
-- Charge for premium listings
-
-**Growth:**
-- 100 agents by end of 2026
-- 10% are paid ($10-100/agent)
-- Average sale: $50 × 10 agents × 200 customers = $100K gross
-- 15% marketplace fee = $15K net
-
-#### Total Revenue Projection
-- **Year 1 (2026):** $1.85M
-  - SaaS: $1M
-  - Enterprise: $500K
-  - Services: $250K
-  - Marketplace: $100K
-
-- **Year 2 (2027):** $9.25M (5x growth)
-  - SaaS: $5M
-  - Enterprise: $3M
-  - Services: $750K
-  - Marketplace: $500K
-
-### Cost Structure
-
-#### Infrastructure (SaaS)
-- Cloud hosting: $50K/year (Year 1) → $250K (Year 2)
-- CDN/bandwidth: $10K/year → $50K
-- Monitoring/logging: $5K/year → $20K
-
-#### Team
-**Year 1 (Lean):**
-- 2 engineers (full-time): $300K
-- 1 DevRel: $120K
-- 1 part-time designer: $50K
-- Founder (you): sweat equity
-
-**Year 2 (Growth):**
-- 5 engineers: $750K
-- 2 DevRel: $240K
-- 1 PM: $150K
-- 1 sales: $150K
-- 1 designer: $100K
-- Founder salary: $150K
-
-#### Marketing
-- Content creation: $30K/year
-- Conferences/events: $50K/year
-- Ads/SEO: $20K/year
-
-#### Total Costs
-- **Year 1:** $635K
-- **Year 2:** $1.78M
-
-### Profitability
-- **Year 1:** $1.85M - $635K = **$1.21M profit** (65% margin)
-- **Year 2:** $9.25M - $1.78M = **$7.47M profit** (81% margin)
-
-**Why such high margins?**
-- Software = low marginal cost
-- Open-source drives adoption (low CAC)
-- Self-service model (low sales cost)
-- High customer retention (sticky product)
-
-### Funding Strategy
-
-#### Bootstrap Path (Recommended)
-- Start with consulting revenue
-- Launch SaaS with freemium model
-- Grow organically from profits
-- No dilution, full control
-
-#### VC Path (If Scaling Faster)
-- Raise $2M seed at $8M pre-money
-- Deploy for:
-  - 2x engineering team
-  - 2x marketing budget
-  - Faster enterprise sales
-- Target: $10M ARR in 18 months
-- Series A: $15M at $50M valuation
-
-**Recommendation:** Bootstrap first, then raise Series A if needed for expansion.
-
----
-
-## Success Metrics
-
-### Technical KPIs
-- [ ] 95%+ of Claude Desktop users can add go-micro services (stdio MCP)
-- [ ] 10,000+ services exposed via MCP in production
-- [ ] <100ms p99 latency for tool discovery
-- [ ] Support 10K concurrent agent requests per gateway
-- [ ] 99.9% MCP gateway uptime
-
-### Business KPIs
-- [ ] $1.85M ARR by end of 2026
-- [ ] 100+ paying SaaS customers
-- [ ] 20+ enterprise deals
-- [ ] 15K+ GitHub stars
-- [ ] 5K+ Discord members
-- [ ] 100+ agents in marketplace
-
-### Community KPIs
-- [ ] 50+ conference talks mentioning go-micro + MCP
-- [ ] 1M+ blog views
-- [ ] 100+ community-contributed examples
-- [ ] 20+ case studies published
-
----
-
-## Risk Mitigation
-
-### Technical Risks
-
-**Risk:** MCP protocol changes (Anthropic controls spec)
-- **Mitigation:** Stay involved in MCP working group, implement protocol versions
-
-**Risk:** Performance issues at scale
-- **Mitigation:** Benchmark early, optimize hot paths, use caching aggressively
-
-**Risk:** Security vulnerabilities in MCP gateway
-- **Mitigation:** Security audits, bug bounty program, responsible disclosure
-
-### Business Risks
-
-**Risk:** AI hype dies down
-- **Mitigation:** Go Micro still works as regular microservices framework. MCP is additive, not core.
-
-**Risk:** Competitors build MCP support
-- **Mitigation:** First-mover advantage, best integration, agent marketplace moat
-
-**Risk:** Cloud providers offer competing solutions
-- **Mitigation:** Open source = no vendor lock-in. We're the community choice.
-
-### Market Risks
-
-**Risk:** Enterprises slow to adopt agents
-- **Mitigation:** Focus on startups first (faster adoption), build proof points
-
-**Risk:** Different MCP implementations fragment market
-- **Mitigation:** Support multiple protocols, be the most compatible
-
----
-
-## Competitive Landscape
-
-### Direct Competitors
-- **Spring Boot** - Java, no MCP support (yet)
-- **Express.js** - JavaScript, minimal microservices support
-- **gRPC-based frameworks** - No MCP support
-
-**Our advantage:** First-mover in MCP + microservices space.
-
-### Indirect Competitors
-- **API Gateway vendors** (Kong, Tyk) - Could add MCP support
-- **Service meshes** (Istio, Linkerd) - Focus on ops, not AI
-
-**Our advantage:** Purpose-built for agent integration, not retrofitted.
-
-### Potential Threats
-- **AWS/GCP/Azure** building managed MCP gateways
-- **Anthropic** launching their own microservices framework
-
-**Defense:**
-- Open source = community ownership
-- Best DX (developer experience)
-- Agent marketplace = network effects
-
----
-
-## Key Integrations Priority
-
-### Tier 1: Must-Have (Q2 2026)
-1. **Claude Desktop** (stdio MCP) - Anthropic's flagship IDE
-2. **ChatGPT Plugins** - Largest user base
-3. **Kubernetes** - Production deployment
-4. **OpenTelemetry** - Observability standard
-
-### Tier 2: Important (Q3 2026)
-5. **LangChain** - Popular agent framework
-6. **Google Gemini** - Major AI player
-7. **Consul/etcd** - Service discovery for enterprise
-8. **Vault** - Secrets management
-
-### Tier 3: Nice-to-Have (Q4 2026)
-9. **LlamaIndex** - RAG and data
-10. **AutoGPT** - Autonomous agents
-11. **Microsoft Copilot** - Enterprise AI
-12. **AWS Bedrock** - Multi-model platform
-
----
-
-## Sustainability Principles
-
-### Open Source Sustainability
-1. **Core stays free** - Framework, basic MCP, CLI always open source
-2. **Community-first** - Features users want, not just what we want to build
-3. **Transparent roadmap** - This document is public
-4. **Contributor recognition** - Credit and compensation for contributions
-
-### Business Sustainability
-1. **Clear value ladder** - Free → SaaS → Enterprise (logical upgrade path)
-2. **High margins** - Software business scales without linear costs
-3. **Multiple revenue streams** - Don't depend on one customer segment
-4. **Profitable by default** - Revenue exceeds costs from Year 1
-
-### Technical Sustainability
-1. **Backward compatibility** - No breaking changes in v5.x
-2. **Stable interfaces** - MCP gateway API won't change unexpectedly
-3. **Performance first** - Fast by default, not through hacks
-4. **Documentation** - Every feature is documented
-
----
-
-## Call to Action
-
-### For Contributors
-- Pick a roadmap item
-- Open an issue to discuss
-- Submit a PR
-- Join Discord for coordination
-
-### For Users
-- Try MCP with your services
-- Share feedback (what works, what doesn't)
-- Write case studies
-- Star the repo ⭐
-
-### For Companies
-- Become a design partner (help shape roadmap)
-- Pilot Go Micro Cloud (early access)
-- Sponsor development (your priorities get built first)
-- Hire us for consulting
-
-### For Investors
-- This is a $100M+ opportunity
-- Agents need microservices
-- We're the first to bridge them
-- Contact: [your-email]
-
----
-
-## Conclusion
-
-**The future of microservices is AI-native.**
-
-API gateways connected apps to services.
-MCP connects agents to services.
-
-Go Micro is uniquely positioned to own this space:
-- ✅ First MCP integration in a major framework
-- ✅ Library-first (not just CLI)
-- ✅ Production-ready from day one
-- ✅ Clear path to monetization
-
-**The question isn't whether agents will use microservices.**
-**The question is: which framework will they use?**
-
-Let's make it Go Micro.
-
----
-
-**Next Steps:**
-1. Review this roadmap with community (GitHub Discussions)
-2. Prioritize Q2 2026 items based on feedback
-3. Start building (stdio MCP first)
-4. Launch Go Micro Cloud beta
-5. Ship fast, iterate faster
-
-**Questions? Feedback?**
-- GitHub Discussions: https://github.com/micro/go-micro/discussions
-- Discord: https://discord.gg/jwTYuUVAGh
-
----
-
-_This roadmap is a living document. It will evolve based on market feedback, technical discoveries, and community input. Last updated: February 2026._

SECURITY.md

@@ -174,6 +174,6 @@ We currently do not offer a bug bounty program, but we greatly appreciate respon
 
 For security questions that are not vulnerabilities, please:
 - Open a discussion: https://github.com/micro/go-micro/discussions
-- Join Discord: https://discord.gg/jwTYuUVAGh
+- Join Discord: https://discord.gg/WeMU5AGxD
 - Email: support@go-micro.dev
 

SUPPORT.md

@@ -0,0 +1,29 @@
+# Support
+
+Go Micro is free and open source. There are two ways to get help: the community, and commercial support.
+
+## Community support (free)
+
+- **Documentation** — https://go-micro.dev/docs
+- **Examples** — https://github.com/micro/go-micro/tree/master/examples
+- **Bugs & features** — https://github.com/micro/go-micro/issues
+- **Questions** — open a [Question](https://github.com/micro/go-micro/issues/new?template=question.md) issue
+
+Community support is best-effort, from maintainers and contributors, with no response-time guarantees.
+
+## Commercial support
+
+If you're running Go Micro in production — or building agents and services on it and want a hand — paid support and consulting are available directly from the maintainer. This is what keeps the project maintained.
+
+| Tier | For | What you get | How |
+|------|-----|--------------|-----|
+| **Community** | Everyone | Docs, examples, issues — best-effort | Free |
+| **Sponsor** | Individuals & companies who rely on Go Micro | Back ongoing development; your name/logo in the README and on the site; a voice in priorities | [GitHub Sponsors](https://github.com/sponsors/asim) |
+| **Support** | Teams running Go Micro in production | Priority responses, a direct line to the maintainer, prioritized bug fixes, upgrade & integration help | [Open a request](#get-in-touch) |
+| **Consulting** | Teams building on Go Micro | Hands-on integration, architecture & agent-design review, training & onboarding, sponsored features | [Open a request](#get-in-touch) |
+
+Recurring amounts are set on the [Sponsors page](https://github.com/sponsors/asim); support and consulting are scoped and quoted per engagement.
+
+## Get in touch
+
+Open a [**Commercial Support / Consulting**](https://github.com/micro/go-micro/issues/new?template=commercial_support.md) request — tell us what you're building, what you need, and your timeline, and we'll follow up. For anything you'd rather not discuss in public, become a [sponsor](https://github.com/sponsors/asim) and message privately.

agent/agent.go

@@ -0,0 +1,348 @@
+// Package agent provides the Agent abstraction for Go Micro.
+//
+// An Agent is a service with an LLM inside it. It registers a Chat
+// RPC endpoint, discovers its assigned services' tools, and
+// orchestrates them intelligently.
+//
+//	agent := micro.NewAgent("task-mgr",
+//	    micro.AgentServices("task"),
+//	    micro.AgentPrompt("You manage tasks."),
+//	    micro.AgentProvider("anthropic"),
+//	)
+//	agent.Run()
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+	"sync"
+
+	"github.com/google/uuid"
+	pb "go-micro.dev/v6/agent/proto"
+	"go-micro.dev/v6/ai"
+	"go-micro.dev/v6/gateway/a2a"
+	"go-micro.dev/v6/server"
+	"go-micro.dev/v6/store"
+
+	_ "go-micro.dev/v6/ai/anthropic"
+	_ "go-micro.dev/v6/ai/atlascloud"
+	_ "go-micro.dev/v6/ai/gemini"
+	_ "go-micro.dev/v6/ai/groq"
+	_ "go-micro.dev/v6/ai/mistral"
+	_ "go-micro.dev/v6/ai/openai"
+	_ "go-micro.dev/v6/ai/together"
+)
+
+// Agent is the interface for an AI agent that manages services.
+type Agent interface {
+	Name() string
+	Init(...Option)
+	Options() Options
+	Ask(ctx context.Context, message string) (*Response, error)
+	Run() error
+	Stop() error
+	String() string
+}
+
+// Response is what an agent returns from Chat.
+type Response struct {
+	Reply     string
+	ToolCalls []ai.ToolCall
+	Agent     string
+}
+
+type agentImpl struct {
+	opts   Options
+	model  ai.Model
+	tools  *ai.Tools
+	mem    Memory
+	server server.Server
+	mu     sync.Mutex
+
+	// ephemeral marks a short-lived sub-agent created by delegation.
+	// Ephemeral agents run with an isolated context: they load and
+	// persist no history, and have no built-in tools (so they cannot
+	// plan or re-delegate).
+	ephemeral bool
+
+	// steps counts tool executions in the current Ask, for MaxSteps.
+	steps int
+	// calls counts identical tool calls (name+args) in the current Ask,
+	// for LoopLimit.
+	calls map[string]int
+
+	// runID correlates the tool calls of the current Ask; parentRunID is
+	// the run that delegated to this one (set on ephemeral sub-agents).
+	// Both are surfaced to tool wrappers via ai.RunInfo on the context.
+	runID       string
+	parentRunID string
+}
+
+// New creates a new Agent.
+func New(opts ...Option) Agent {
+	return &agentImpl{
+		opts: newOptions(opts...),
+	}
+}
+
+// newEphemeral creates a short-lived sub-agent for a delegated subtask.
+// It shares the parent's provider, model, and infrastructure but runs
+// with an isolated context: it loads and persists no history and has no
+// built-in tools (so it can neither plan nor re-delegate). Returns the
+// concrete type because ephemeral is an internal construction detail,
+// not a public option.
+func newEphemeral(opts ...Option) *agentImpl {
+	return &agentImpl{
+		opts:      newOptions(opts...),
+		ephemeral: true,
+	}
+}
+
+func (a *agentImpl) Name() string {
+	return a.opts.Name
+}
+
+func (a *agentImpl) Init(opts ...Option) {
+	for _, o := range opts {
+		o(&a.opts)
+	}
+	a.setup()
+}
+
+func (a *agentImpl) Options() Options {
+	return a.opts
+}
+
+func (a *agentImpl) String() string {
+	return "agent"
+}
+
+func (a *agentImpl) setup() {
+	var modelOpts []ai.Option
+	modelOpts = append(modelOpts, ai.WithAPIKey(a.opts.APIKey))
+	if a.opts.Model != "" {
+		modelOpts = append(modelOpts, ai.WithModel(a.opts.Model))
+	}
+
+	a.tools = ai.NewTools(a.opts.Registry, ai.ToolClient(a.opts.Client))
+	modelOpts = append(modelOpts, ai.WithToolHandler(a.toolHandler()))
+	a.model = ai.New(a.opts.Provider, modelOpts...)
+
+	// Memory is pluggable. Use the configured one, otherwise the default
+	// store-backed memory — except ephemeral sub-agents, which keep an
+	// isolated, non-persistent context.
+	switch {
+	case a.opts.Memory != nil:
+		a.mem = a.opts.Memory
+	case a.ephemeral:
+		a.mem = NewInMemory(a.opts.HistoryLimit)
+	default:
+		a.mem = NewMemory(a.stateStore(), "history", a.opts.HistoryLimit)
+	}
+}
+
+// stateStore returns the agent's own state store, scoped to its name so
+// memory and plan live in their own table ("agent/{name}") rather than a
+// shared global one. The scoped handle injects the database/table per
+// operation without mutating the underlying store.
+func (a *agentImpl) stateStore() store.Store {
+	s := a.opts.Store
+	if s == nil {
+		s = store.DefaultStore
+	}
+	return store.Scope(s, "agent", a.opts.Name)
+}
+
+// Ask sends a message and returns the agent's response.
+// This is the programmatic API for direct use.
+func (a *agentImpl) Ask(ctx context.Context, message string) (*Response, error) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	if a.model == nil {
+		a.setup()
+	}
+
+	toolList, err := a.discoverTools()
+	if err != nil {
+		return nil, fmt.Errorf("discover tools: %w", err)
+	}
+
+	a.mem.Add("user", message)
+	a.steps = 0
+	a.calls = map[string]int{}
+
+	// Correlate this run's tool calls and surface lineage to wrappers.
+	a.runID = uuid.New().String()
+	ctx = ai.WithRunInfo(ctx, ai.RunInfo{
+		RunID:    a.runID,
+		ParentID: a.parentRunID,
+		Agent:    a.opts.Name,
+	})
+
+	resp, err := a.model.Generate(ctx, &ai.Request{
+		Prompt:       message,
+		SystemPrompt: a.buildPrompt(),
+		Tools:        toolList,
+		Messages:     a.mem.Messages(),
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	if resp.Reply != "" {
+		a.mem.Add("assistant", resp.Reply)
+	}
+	if resp.Answer != "" {
+		a.mem.Add("assistant", resp.Answer)
+	}
+
+	reply := resp.Reply
+	if resp.Answer != "" {
+		if reply != "" {
+			reply += "\n\n"
+		}
+		reply += resp.Answer
+	}
+
+	return &Response{
+		Reply:     reply,
+		ToolCalls: resp.ToolCalls,
+		Agent:     a.opts.Name,
+	}, nil
+}
+
+// Chat implements the proto AgentHandler interface for RPC.
+// @example {"message": "What tasks are overdue?"}
+func (a *agentImpl) Chat(ctx context.Context, req *pb.ChatRequest, rsp *pb.ChatResponse) error {
+	resp, err := a.Ask(ctx, req.Message)
+	if err != nil {
+		return err
+	}
+	rsp.Reply = resp.Reply
+	rsp.Agent = resp.Agent
+	for _, tc := range resp.ToolCalls {
+		input, _ := json.Marshal(tc.Input)
+		rsp.ToolCalls = append(rsp.ToolCalls, &pb.ToolCall{
+			Id:     tc.ID,
+			Name:   tc.Name,
+			Input:  string(input),
+			Result: tc.Result,
+		})
+	}
+	return nil
+}
+
+// Run starts the agent as a service with a Chat RPC endpoint.
+func (a *agentImpl) Run() error {
+	if a.model == nil {
+		a.setup()
+	}
+
+	a.server = server.NewServer(
+		server.Name(a.opts.Name),
+		server.Registry(a.opts.Registry),
+		server.Metadata(map[string]string{
+			"type":     "agent",
+			"services": strings.Join(a.opts.Services, ","),
+		}),
+	)
+
+	_ = pb.RegisterAgentHandler(a.server, a)
+
+	if err := a.server.Start(); err != nil {
+		return fmt.Errorf("failed to start agent: %w", err)
+	}
+
+	fmt.Printf("Agent %s registered (manages: %s)\n", a.opts.Name, strings.Join(a.opts.Services, ", "))
+
+	// Optionally serve the agent directly over the A2A protocol, calling
+	// Ask in-process — no separate gateway needed to be queried by URL.
+	if a.opts.A2AAddress != "" {
+		card := a2a.Card(a.opts.Name, "http://localhost"+a.opts.A2AAddress, "", a.opts.Services)
+		handler := a2a.NewAgentHandler(card, func(ctx context.Context, text string) (string, error) {
+			resp, err := a.Ask(ctx, text)
+			if err != nil {
+				return "", err
+			}
+			return resp.Reply, nil
+		})
+		go func() {
+			if err := http.ListenAndServe(a.opts.A2AAddress, handler); err != nil {
+				fmt.Printf("agent %s A2A server: %v\n", a.opts.Name, err)
+			}
+		}()
+		fmt.Printf("Agent %s serving A2A on %s\n", a.opts.Name, a.opts.A2AAddress)
+	}
+
+	ch := make(chan struct{})
+	<-ch
+	return nil
+}
+
+func (a *agentImpl) Stop() error {
+	if a.server != nil {
+		return a.server.Stop()
+	}
+	return nil
+}
+
+func (a *agentImpl) discoverTools() ([]ai.Tool, error) {
+	all, err := a.tools.Discover()
+	if err != nil {
+		return nil, err
+	}
+
+	var scoped []ai.Tool
+	for _, t := range all {
+		if strings.HasPrefix(t.OriginalName, a.opts.Name+".") {
+			continue
+		}
+		if len(a.opts.Services) == 0 {
+			scoped = append(scoped, t)
+			continue
+		}
+		for _, svc := range a.opts.Services {
+			if strings.HasPrefix(t.OriginalName, svc+".") {
+				scoped = append(scoped, t)
+				break
+			}
+		}
+	}
+
+	// Developer-registered custom tools (WithTool).
+	for i := range a.opts.tools {
+		scoped = append(scoped, a.opts.tools[i].def)
+	}
+
+	// Expose the agent's own capabilities (plan, delegate) as tools.
+	// Ephemeral sub-agents don't get them.
+	if !a.ephemeral {
+		scoped = append(scoped, builtinTools()...)
+	}
+	return scoped, nil
+}
+
+func (a *agentImpl) buildPrompt() string {
+	var base string
+	switch {
+	case a.opts.Prompt != "":
+		base = a.opts.Prompt
+	case len(a.opts.Services) > 0:
+		base = fmt.Sprintf("You are the %s agent. You manage these services: %s. Use the available tools to fulfill requests.",
+			a.opts.Name, strings.Join(a.opts.Services, ", "))
+	default:
+		base = fmt.Sprintf("You are the %s agent. Use the available tools to fulfill requests.", a.opts.Name)
+	}
+
+	// Keep the agent oriented: surface its saved plan, if any.
+	if !a.ephemeral {
+		if plan := a.loadPlan(); plan != "" {
+			base += "\n\nYour current plan (update it with the plan tool as you make progress):\n" + plan
+		}
+	}
+	return base
+}

agent/agent_test.go

@@ -0,0 +1,88 @@
+package agent
+
+import (
+	"testing"
+)
+
+func TestNew(t *testing.T) {
+	a := New(
+		Name("test-agent"),
+		Services("task", "project"),
+		Prompt("You manage tasks."),
+		Provider("anthropic"),
+	)
+
+	if a.Name() != "test-agent" {
+		t.Errorf("Name() = %q, want %q", a.Name(), "test-agent")
+	}
+
+	opts := a.Options()
+	if opts.Provider != "anthropic" {
+		t.Errorf("Provider = %q, want %q", opts.Provider, "anthropic")
+	}
+	if len(opts.Services) != 2 {
+		t.Fatalf("Services = %v, want 2 items", opts.Services)
+	}
+	if opts.Services[0] != "task" || opts.Services[1] != "project" {
+		t.Errorf("Services = %v, want [task project]", opts.Services)
+	}
+	if opts.Prompt != "You manage tasks." {
+		t.Errorf("Prompt = %q, want %q", opts.Prompt, "You manage tasks.")
+	}
+	if opts.HistoryLimit != 50 {
+		t.Errorf("HistoryLimit = %d, want 50", opts.HistoryLimit)
+	}
+}
+
+func TestBuildPrompt(t *testing.T) {
+	// Custom prompt
+	a := New(Name("test"), Prompt("custom prompt")).(*agentImpl)
+	if got := a.buildPrompt(); got != "custom prompt" {
+		t.Errorf("buildPrompt() = %q, want %q", got, "custom prompt")
+	}
+
+	// Auto-generated prompt with services
+	a = New(Name("test"), Services("task", "project")).(*agentImpl)
+	got := a.buildPrompt()
+	if got == "" {
+		t.Error("buildPrompt() returned empty")
+	}
+	if !contains(got, "task") || !contains(got, "project") {
+		t.Errorf("buildPrompt() = %q, should mention services", got)
+	}
+
+	// Auto-generated prompt without services
+	a = New(Name("test")).(*agentImpl)
+	got = a.buildPrompt()
+	if !contains(got, "test") {
+		t.Errorf("buildPrompt() = %q, should mention agent name", got)
+	}
+}
+
+func TestDefaults(t *testing.T) {
+	a := New(Name("test"))
+	opts := a.Options()
+
+	if opts.Registry == nil {
+		t.Error("Registry should default to DefaultRegistry")
+	}
+	if opts.Client == nil {
+		t.Error("Client should default to DefaultClient")
+	}
+	if opts.Store == nil {
+		t.Error("Store should default to DefaultStore")
+	}
+}
+
+func contains(s, sub string) bool {
+	return len(s) >= len(sub) && (s == sub || len(s) > 0 && containsStr(s, sub))
+}
+
+func containsStr(s, sub string) bool {
+	for i := 0; i <= len(s)-len(sub); i++ {
+		if s[i:i+len(sub)] == sub {
+			return true
+		}
+	}
+	return false
+}

agent/builtin.go

@@ -0,0 +1,340 @@
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"go-micro.dev/v6/ai"
+	codecBytes "go-micro.dev/v6/codec/bytes"
+	"go-micro.dev/v6/gateway/a2a"
+	"go-micro.dev/v6/store"
+)
+
+// Built-in agent tools. These are not service endpoints — they are
+// capabilities the agent has over itself: maintaining a plan in its
+// memory, and delegating a subtask to another agent.
+//
+// They are plain tools, wired into the agent's tool handler alongside
+// the discovered service tools. There is no separate harness or graph:
+// the LLM calls them like any other tool.
+const (
+	toolPlan     = "plan"
+	toolDelegate = "delegate"
+)
+
+// builtinTools returns the tool definitions exposed to the model in
+// addition to the agent's scoped service tools.
+func builtinTools() []ai.Tool {
+	return []ai.Tool{
+		{
+			Name:         toolPlan,
+			OriginalName: toolPlan,
+			Description: "Record or update your plan as an ordered list of steps before doing multi-step work. " +
+				"Call this whenever the plan changes. The plan is saved to your memory and shown back to you on later turns.",
+			Properties: map[string]any{
+				"steps": map[string]any{
+					"type": "array",
+					"description": "Ordered plan steps. Each step has a 'task' (string) and a " +
+						"'status' (one of: pending, in_progress, done).",
+				},
+			},
+		},
+		{
+			Name:         toolDelegate,
+			OriginalName: toolDelegate,
+			Description: "Delegate a self-contained subtask to another agent. If 'to' names an agent that already " +
+				"manages the relevant services, that agent handles it; otherwise a focused sub-agent is created for the " +
+				"subtask. The sub-agent works in an isolated context and returns only its result. Use this to keep your " +
+				"own context focused and to let domain experts handle their own services.",
+			Properties: map[string]any{
+				"task": map[string]any{
+					"type":        "string",
+					"description": "The subtask to delegate, described completely and self-contained.",
+				},
+				"to": map[string]any{
+					"type":        "string",
+					"description": "Optional. The agent or service name best suited to the subtask, or the URL of an external agent that speaks the A2A protocol.",
+				},
+			},
+		},
+	}
+}
+
+// Builtins returns the built-in agent tools (plan, delegate) together
+// with a handler for them, so the same capabilities can be wired into a
+// tool loop that isn't a running Agent — for example the `micro chat`
+// fallback. The handler's third return value is false when the name is
+// not a built-in, so callers can fall through to their own tools.
+//
+// Configure it with the same options as an Agent (Name, Provider,
+// WithStore, WithRegistry, WithClient, ...); these back plan's memory
+// and delegate's RPC/sub-agent behavior.
+func Builtins(opts ...Option) (tools []ai.Tool, handle func(name string, input map[string]any) (result any, content string, ok bool)) {
+	a := &agentImpl{opts: newOptions(opts...)}
+	handle = func(name string, input map[string]any) (any, string, bool) {
+		switch name {
+		case toolPlan:
+			r := a.handlePlan(ai.ToolCall{Name: name, Input: input})
+			return r.Value, r.Content, true
+		case toolDelegate:
+			r := a.handleDelegate(ai.ToolCall{Name: name, Input: input})
+			return r.Value, r.Content, true
+		}
+		return nil, "", false
+	}
+	return builtinTools(), handle
+}
+
+// toolHandler returns the agent's tool-call handler, composed as a stack
+// of wrappers around a base handler — the same middleware shape as
+// client/server wrappers. The base executes the call (custom tools,
+// delegate, or RPC); the built-in guardrails wrap it; developer wrappers
+// (WrapTool) wrap those, outermost, so they observe every call and its
+// result including guardrail refusals. Ephemeral sub-agents get the bare
+// service handler so they can neither plan nor re-delegate (which
+// prevents runaway recursion).
+func (a *agentImpl) toolHandler() ai.ToolHandler {
+	if a.ephemeral {
+		return a.tools.Handler()
+	}
+
+	// Innermost first: base, then guardrails (approve → loop → step →
+	// plan), then developer wrappers outermost. Wrapping reverses order,
+	// so the result runs plan → step → loop → approve → base.
+	h := a.baseHandler()
+	h = a.approveWrap(h)
+	h = a.loopWrap(h)
+	h = a.stepWrap(h)
+	h = a.planWrap(h)
+	for i := len(a.opts.wrappers) - 1; i >= 0; i-- {
+		h = a.opts.wrappers[i](h)
+	}
+	return h
+}
+
+// baseHandler executes a tool call: a developer custom tool, the built-in
+// delegate, or an RPC to the service. It is the innermost handler.
+func (a *agentImpl) baseHandler() ai.ToolHandler {
+	rpc := a.tools.Handler()
+	return func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
+		for i := range a.opts.tools {
+			if a.opts.tools[i].def.Name == call.Name {
+				out, err := a.opts.tools[i].handler(ctx, call.Input)
+				if err != nil {
+					return errResult(call.ID, err.Error())
+				}
+				return ai.ToolResult{ID: call.ID, Value: out, Content: out}
+			}
+		}
+		if call.Name == toolDelegate {
+			return a.handleDelegate(call)
+		}
+		return rpc(ctx, call)
+	}
+}
+
+// planWrap handles the plan tool inline. plan is internal bookkeeping,
+// not an action — it is never counted, loop-checked, or gated.
+func (a *agentImpl) planWrap(next ai.ToolHandler) ai.ToolHandler {
+	return func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
+		if call.Name == toolPlan {
+			return a.handlePlan(call)
+		}
+		return next(ctx, call)
+	}
+}
+
+// stepWrap bounds the number of actions per Ask (MaxSteps).
+func (a *agentImpl) stepWrap(next ai.ToolHandler) ai.ToolHandler {
+	return func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
+		if a.opts.MaxSteps > 0 {
+			a.steps++
+			if a.steps > a.opts.MaxSteps {
+				return refused(call.ID, ai.RefusedMaxSteps, fmt.Sprintf(
+					"step limit reached (%d). Do not call any more tools; stop and summarize what you have so far.",
+					a.opts.MaxSteps))
+			}
+		}
+		return next(ctx, call)
+	}
+}
+
+// loopWrap stops the agent repeating an identical action that makes no
+// progress (which the step count alone won't catch).
+func (a *agentImpl) loopWrap(next ai.ToolHandler) ai.ToolHandler {
+	return func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
+		if a.opts.LoopLimit > 0 {
+			if a.calls == nil {
+				a.calls = map[string]int{}
+			}
+			args, _ := json.Marshal(call.Input)
+			fp := call.Name + ":" + string(args)
+			a.calls[fp]++
+			if a.calls[fp] > a.opts.LoopLimit {
+				return refused(call.ID, ai.RefusedLoop, fmt.Sprintf(
+					"loop detected: you have already called %q with the same arguments %d times and the result will not change. Stop repeating it — try a different approach, or finish with what you have.",
+					call.Name, a.opts.LoopLimit))
+			}
+		}
+		return next(ctx, call)
+	}
+}
+
+// approveWrap gates each action before it runs (ApproveTool).
+func (a *agentImpl) approveWrap(next ai.ToolHandler) ai.ToolHandler {
+	return func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
+		if a.opts.Approve != nil {
+			if ok, reason := a.opts.Approve(call.Name, call.Input); !ok {
+				msg := "tool call was not approved"
+				if reason != "" {
+					msg += ": " + reason
+				}
+				return refused(call.ID, ai.RefusedApproval, msg)
+			}
+		}
+		return next(ctx, call)
+	}
+}
+
+// handlePlan persists the supplied plan to the agent's memory and
+// echoes it back so the model can see the stored state.
+func (a *agentImpl) handlePlan(call ai.ToolCall) ai.ToolResult {
+	data, err := json.Marshal(call.Input)
+	if err != nil {
+		return errResult(call.ID, "invalid plan: "+err.Error())
+	}
+	_ = a.stateStore().Write(&store.Record{Key: planKey, Value: data})
+	return ai.ToolResult{ID: call.ID, Value: call.Input, Content: string(data)}
+}
+
+// handleDelegate hands a subtask to another agent. Delegate-first:
+// if 'to' names a registered agent, it is called via RPC. Otherwise an
+// ephemeral sub-agent is created with a fresh, isolated context, asked
+// the subtask, and its reply returned.
+func (a *agentImpl) handleDelegate(call ai.ToolCall) ai.ToolResult {
+	input := call.Input
+	task, _ := input["task"].(string)
+	if task == "" {
+		return errResult(call.ID, "task is required")
+	}
+	to, _ := input["to"].(string)
+
+	// An external agent on another framework, addressed by A2A URL.
+	if strings.HasPrefix(to, "http://") || strings.HasPrefix(to, "https://") {
+		reply, err := a2a.NewClient(to).Send(context.Background(), task)
+		if err != nil {
+			return errResult(call.ID, "delegate to A2A agent "+to+": "+err.Error())
+		}
+		out := map[string]any{"agent": to, "reply": reply}
+		b, _ := json.Marshal(out)
+		return ai.ToolResult{ID: call.ID, Value: out, Content: string(b)}
+	}
+
+	// Delegate-first: an existing agent that owns the domain handles it.
+	if to != "" && a.isAgent(to) {
+		reply, err := a.callAgentRPC(context.Background(), to, task)
+		if err != nil {
+			return errResult(call.ID, "delegate to agent "+to+": "+err.Error())
+		}
+		out := map[string]any{"agent": to, "reply": reply}
+		b, _ := json.Marshal(out)
+		return ai.ToolResult{ID: call.ID, Value: out, Content: string(b)}
+	}
+
+	// Otherwise create a focused, ephemeral sub-agent. Fresh context:
+	// it loads no history and persists none.
+	var svcs []string
+	if to != "" {
+		svcs = []string{to}
+	}
+	sub := newEphemeral(
+		Name(a.opts.Name+".sub"),
+		Services(svcs...),
+		Prompt("You are a sub-agent handling a single delegated subtask. "+
+			"Complete it using the available tools and report the result concisely."),
+		Provider(a.opts.Provider),
+		Model(a.opts.Model),
+		APIKey(a.opts.APIKey),
+		WithRegistry(a.opts.Registry),
+		WithClient(a.opts.Client),
+		WithStore(a.opts.Store),
+	)
+	// Record lineage so the sub-agent's tool calls carry this run as parent.
+	sub.parentRunID = a.runID
+
+	resp, err := sub.Ask(context.Background(), task)
+	if err != nil {
+		return errResult(call.ID, "sub-agent: "+err.Error())
+	}
+	out := map[string]any{"reply": resp.Reply}
+	b, _ := json.Marshal(out)
+	return ai.ToolResult{ID: call.ID, Value: out, Content: string(b)}
+}
+
+// isAgent reports whether name resolves to a registered agent (a
+// service advertising type=agent in its metadata).
+func (a *agentImpl) isAgent(name string) bool {
+	if a.opts.Registry == nil {
+		return false
+	}
+	recs, err := a.opts.Registry.GetService(name)
+	if err != nil || len(recs) == 0 {
+		return false
+	}
+	if recs[0].Metadata != nil && recs[0].Metadata["type"] == "agent" {
+		return true
+	}
+	for _, n := range recs[0].Nodes {
+		if n.Metadata != nil && n.Metadata["type"] == "agent" {
+			return true
+		}
+	}
+	return false
+}
+
+// callAgentRPC calls another agent's Agent.Chat endpoint and returns
+// its reply.
+func (a *agentImpl) callAgentRPC(ctx context.Context, name, msg string) (string, error) {
+	body, _ := json.Marshal(map[string]string{"message": msg})
+	req := a.opts.Client.NewRequest(name, "Agent.Chat", &codecBytes.Frame{Data: body})
+	var rsp codecBytes.Frame
+	if err := a.opts.Client.Call(ctx, req, &rsp); err != nil {
+		return "", err
+	}
+	var out struct {
+		Reply string `json:"reply"`
+	}
+	if err := json.Unmarshal(rsp.Data, &out); err != nil {
+		return "", err
+	}
+	return out.Reply, nil
+}
+
+// planKey is the record key for an agent's plan within its scoped store.
+const planKey = "plan"
+
+// loadPlan returns the stored plan as a JSON string, or "" if none.
+func (a *agentImpl) loadPlan() string {
+	recs, err := a.stateStore().Read(planKey)
+	if err != nil || len(recs) == 0 {
+		return ""
+	}
+	return string(recs[0].Value)
+}
+
+func errResult(id, msg string) ai.ToolResult {
+	m := map[string]string{"error": msg}
+	b, _ := json.Marshal(m)
+	return ai.ToolResult{ID: id, Value: m, Content: string(b)}
+}
+
+// refused is an error result a guardrail returns, tagged with a structured
+// reason (ai.Refused*) so a tool wrapper can react to it without parsing
+// the message.
+func refused(id, reason, msg string) ai.ToolResult {
+	r := errResult(id, msg)
+	r.Refused = reason
+	return r
+}

agent/builtin_test.go

@@ -0,0 +1,167 @@
+package agent
+
+import (
+	"encoding/json"
+	"testing"
+
+	"go-micro.dev/v6/ai"
+	"go-micro.dev/v6/registry"
+	"go-micro.dev/v6/store"
+)
+
+func TestBuiltinTools(t *testing.T) {
+	tools := builtinTools()
+	if len(tools) != 2 {
+		t.Fatalf("builtinTools() = %d tools, want 2", len(tools))
+	}
+	names := map[string]bool{}
+	for _, tl := range tools {
+		names[tl.Name] = true
+	}
+	if !names[toolPlan] || !names[toolDelegate] {
+		t.Errorf("builtin tools = %v, want plan and delegate", names)
+	}
+}
+
+func TestHandlePlanPersists(t *testing.T) {
+	mem := store.NewMemoryStore()
+	a := New(Name("planner"), WithStore(mem)).(*agentImpl)
+
+	steps := map[string]any{
+		"steps": []any{
+			map[string]any{"task": "gather requirements", "status": "done"},
+			map[string]any{"task": "write code", "status": "in_progress"},
+		},
+	}
+	content := a.handlePlan(ai.ToolCall{Name: "plan", Input: steps}).Content
+	if content == "" {
+		t.Fatal("handlePlan returned empty content")
+	}
+
+	// The plan must be retrievable from memory.
+	got := a.loadPlan()
+	if got == "" {
+		t.Fatal("loadPlan() returned empty after handlePlan")
+	}
+	var decoded map[string]any
+	if err := json.Unmarshal([]byte(got), &decoded); err != nil {
+		t.Fatalf("stored plan is not valid JSON: %v", err)
+	}
+	if _, ok := decoded["steps"]; !ok {
+		t.Errorf("stored plan missing steps: %s", got)
+	}
+}
+
+func TestPlanShowsInPrompt(t *testing.T) {
+	mem := store.NewMemoryStore()
+	a := New(Name("planner"), Prompt("base prompt"), WithStore(mem)).(*agentImpl)
+
+	if got := a.buildPrompt(); got != "base prompt" {
+		t.Errorf("buildPrompt() with no plan = %q, want %q", got, "base prompt")
+	}
+
+	a.handlePlan(ai.ToolCall{Name: "plan", Input: map[string]any{"steps": []any{map[string]any{"task": "do it", "status": "pending"}}}})
+
+	got := a.buildPrompt()
+	if got == "base prompt" {
+		t.Error("buildPrompt() should include the plan once one is saved")
+	}
+	if !containsStr(got, "do it") {
+		t.Errorf("buildPrompt() = %q, should contain the saved plan", got)
+	}
+}
+
+func TestDiscoverToolsIncludesBuiltins(t *testing.T) {
+	reg := registry.NewMemoryRegistry()
+	a := New(Name("a"), WithRegistry(reg), WithStore(store.NewMemoryStore())).(*agentImpl)
+	a.setup()
+
+	tools, err := a.discoverTools()
+	if err != nil {
+		t.Fatalf("discoverTools: %v", err)
+	}
+	// No services registered, so the only tools should be the builtins.
+	if len(tools) != len(builtinTools()) {
+		t.Fatalf("discoverTools() = %d tools, want %d builtins", len(tools), len(builtinTools()))
+	}
+}
+
+func TestEphemeralAgentHasNoBuiltins(t *testing.T) {
+	reg := registry.NewMemoryRegistry()
+	a := New(Name("a.sub"), WithRegistry(reg), WithStore(store.NewMemoryStore())).(*agentImpl)
+	a.ephemeral = true
+	a.setup()
+
+	tools, err := a.discoverTools()
+	if err != nil {
+		t.Fatalf("discoverTools: %v", err)
+	}
+	if len(tools) != 0 {
+		t.Errorf("ephemeral agent discoverTools() = %d tools, want 0", len(tools))
+	}
+}
+
+func TestBuiltinsAccessor(t *testing.T) {
+	mem := store.NewMemoryStore()
+	tools, handle := Builtins(
+		Name("chat"),
+		WithStore(mem),
+		WithRegistry(registry.NewMemoryRegistry()),
+	)
+
+	if len(tools) != 2 {
+		t.Fatalf("Builtins() returned %d tools, want 2", len(tools))
+	}
+
+	// A name that isn't a built-in falls through (ok == false).
+	if _, _, ok := handle("not_a_builtin", nil); ok {
+		t.Error("handle(non-builtin) ok = true, want false")
+	}
+
+	// plan is handled and persisted under the configured name.
+	_, content, ok := handle(toolPlan, map[string]any{
+		"steps": []any{map[string]any{"task": "x", "status": "pending"}},
+	})
+	if !ok {
+		t.Fatal("handle(plan) ok = false, want true")
+	}
+	if content == "" {
+		t.Fatal("handle(plan) returned empty content")
+	}
+	scoped := store.Scope(mem, "agent", "chat")
+	if recs, err := scoped.Read(planKey); err != nil || len(recs) == 0 {
+		t.Errorf("plan not persisted in the agent's scoped store: err=%v recs=%d", err, len(recs))
+	}
+}
+
+func TestIsAgent(t *testing.T) {
+	reg := registry.NewMemoryRegistry()
+
+	// A plain service.
+	if err := reg.Register(&registry.Service{
+		Name:  "task",
+		Nodes: []*registry.Node{{Id: "task-1", Address: "127.0.0.1:0"}},
+	}); err != nil {
+		t.Fatalf("register service: %v", err)
+	}
+	// An agent (advertises type=agent).
+	if err := reg.Register(&registry.Service{
+		Name:     "task-mgr",
+		Metadata: map[string]string{"type": "agent"},
+		Nodes:    []*registry.Node{{Id: "task-mgr-1", Address: "127.0.0.1:0"}},
+	}); err != nil {
+		t.Fatalf("register agent: %v", err)
+	}
+
+	a := New(Name("root"), WithRegistry(reg)).(*agentImpl)
+
+	if a.isAgent("task") {
+		t.Error("isAgent(task) = true, want false (plain service)")
+	}
+	if !a.isAgent("task-mgr") {
+		t.Error("isAgent(task-mgr) = false, want true (agent)")
+	}
+	if a.isAgent("nonexistent") {
+		t.Error("isAgent(nonexistent) = true, want false")
+	}
+}

agent/guardrails_test.go

@@ -0,0 +1,92 @@
+package agent
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"go-micro.dev/v6/ai"
+	"go-micro.dev/v6/registry"
+	"go-micro.dev/v6/store"
+)
+
+// toolContent runs a tool call through a handler and returns the content
+// shown to the model — the part these tests assert on.
+func toolContent(h ai.ToolHandler, name string, input map[string]any) string {
+	return h(context.Background(), ai.ToolCall{Name: name, Input: input}).Content
+}
+
+// MaxSteps refuses tool calls once the per-Ask limit is exceeded; plan
+// is bookkeeping and is never counted.
+func TestMaxStepsStopsActions(t *testing.T) {
+	a := newTestAgent(Name("limited"), MaxSteps(2))
+
+	h := a.toolHandler()
+
+	// plan must not consume a step.
+	a.steps = 0
+	toolContent(h, toolPlan, map[string]any{"steps": []any{}})
+	if a.steps != 0 {
+		t.Fatalf("plan consumed a step: steps=%d", a.steps)
+	}
+
+	// First two actions are allowed (they fall through to RPC, which
+	// fails harmlessly — we only care they weren't refused by the limit).
+	for i := 1; i <= 2; i++ {
+		content := toolContent(h, "demo_Svc_Do", map[string]any{})
+		if strings.Contains(content, "step limit") {
+			t.Fatalf("action %d wrongly hit the step limit", i)
+		}
+	}
+
+	// Third action exceeds MaxSteps(2) and must be refused.
+	content := toolContent(h, "demo_Svc_Do", map[string]any{})
+	if !strings.Contains(content, "step limit") {
+		t.Errorf("third action should hit the step limit; got %q", content)
+	}
+}
+
+// ApproveTool blocks an action when the hook denies it, and the denial
+// reason is surfaced to the model.
+func TestApproveToolBlocks(t *testing.T) {
+	var sawTool string
+	a := newTestAgent(Name("gated"),
+		ApproveTool(func(tool string, input map[string]any) (bool, string) {
+			sawTool = tool
+			return false, "needs sign-off"
+		}),
+	)
+
+	content := toolContent(a.toolHandler(), "demo_Svc_Do", map[string]any{})
+	if sawTool != "demo_Svc_Do" {
+		t.Errorf("approver saw %q, want demo_Svc_Do", sawTool)
+	}
+	if !strings.Contains(content, "not approved") || !strings.Contains(content, "needs sign-off") {
+		t.Errorf("blocked call should surface the reason; got %q", content)
+	}
+}
+
+// A denying approver must not gate the internal plan tool.
+func TestApproveToolDoesNotGatePlan(t *testing.T) {
+	mem := store.NewMemoryStore()
+	a := New(
+		Name("gated"),
+		Provider("fake"),
+		WithRegistry(registry.NewMemoryRegistry()),
+		WithStore(mem),
+		ApproveTool(func(tool string, input map[string]any) (bool, string) {
+			return false, "deny everything"
+		}),
+	).(*agentImpl)
+	a.setup()
+
+	content := toolContent(a.toolHandler(), toolPlan, map[string]any{
+		"steps": []any{map[string]any{"task": "x", "status": "pending"}},
+	})
+	if strings.Contains(content, "not approved") {
+		t.Errorf("plan must not be gated by ApproveTool; got %q", content)
+	}
+	if recs, _ := store.Scope(mem, "agent", "gated").Read(planKey); len(recs) == 0 {
+		t.Error("plan should have been persisted despite the denying approver")
+	}
+}

agent/integration_test.go

@@ -0,0 +1,181 @@
+package agent
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"go-micro.dev/v6/ai"
+	"go-micro.dev/v6/client"
+	codecBytes "go-micro.dev/v6/codec/bytes"
+	"go-micro.dev/v6/registry"
+	"go-micro.dev/v6/store"
+)
+
+// fakeGen drives the fake provider's Generate. Tests set it and reset
+// it with a deferred cleanup. Tests in this package are not parallel,
+// so a package-level hook is safe.
+var fakeGen func(opts ai.Options, req *ai.Request) (*ai.Response, error)
+
+type fakeModel struct{ opts ai.Options }
+
+func (m *fakeModel) Init(opts ...ai.Option) error {
+	for _, o := range opts {
+		o(&m.opts)
+	}
+	return nil
+}
+func (m *fakeModel) Options() ai.Options { return m.opts }
+func (m *fakeModel) Generate(ctx context.Context, req *ai.Request, _ ...ai.GenerateOption) (*ai.Response, error) {
+	if fakeGen != nil {
+		return fakeGen(m.opts, req)
+	}
+	return &ai.Response{Reply: "ok"}, nil
+}
+func (m *fakeModel) Stream(ctx context.Context, req *ai.Request, _ ...ai.GenerateOption) (ai.Stream, error) {
+	return nil, nil
+}
+func (m *fakeModel) String() string { return "fake" }
+
+func init() {
+	ai.Register("fake", func(opts ...ai.Option) ai.Model {
+		m := &fakeModel{}
+		_ = m.Init(opts...)
+		return m
+	})
+}
+
+// fakeClient embeds the default client (so NewRequest works) and
+// overrides Call with a test-supplied function.
+type fakeClient struct {
+	client.Client
+	callFn func(ctx context.Context, req client.Request, rsp interface{}) error
+}
+
+func (c *fakeClient) Call(ctx context.Context, req client.Request, rsp interface{}, opts ...client.CallOption) error {
+	return c.callFn(ctx, req, rsp)
+}
+
+func newTestAgent(opts ...Option) *agentImpl {
+	base := []Option{
+		Provider("fake"),
+		WithRegistry(registry.NewMemoryRegistry()),
+		WithStore(store.NewMemoryStore()),
+	}
+	a := New(append(base, opts...)...).(*agentImpl)
+	a.setup()
+	return a
+}
+
+// The model is offered the plan and delegate tools, and calling the
+// plan tool persists the plan to memory.
+func TestAskExposesAndRunsPlan(t *testing.T) {
+	var sawPlan, sawDelegate bool
+	fakeGen = func(opts ai.Options, req *ai.Request) (*ai.Response, error) {
+		for _, tl := range req.Tools {
+			switch tl.Name {
+			case toolPlan:
+				sawPlan = true
+			case toolDelegate:
+				sawDelegate = true
+			}
+		}
+		// Simulate the model recording a plan.
+		if opts.ToolHandler != nil {
+			opts.ToolHandler(context.Background(), ai.ToolCall{
+				Name: toolPlan,
+				Input: map[string]any{
+					"steps": []any{map[string]any{"task": "step one", "status": "pending"}},
+				},
+			})
+		}
+		return &ai.Response{Answer: "done"}, nil
+	}
+	defer func() { fakeGen = nil }()
+
+	a := newTestAgent(Name("worker"))
+	resp, err := a.Ask(context.Background(), "do some multi-step work")
+	if err != nil {
+		t.Fatalf("Ask: %v", err)
+	}
+	if !sawPlan || !sawDelegate {
+		t.Errorf("model should be offered plan and delegate tools: plan=%v delegate=%v", sawPlan, sawDelegate)
+	}
+	if resp.Reply == "" {
+		t.Error("Ask returned empty reply")
+	}
+	if plan := a.loadPlan(); !strings.Contains(plan, "step one") {
+		t.Errorf("plan tool result not persisted; loadPlan() = %q", plan)
+	}
+}
+
+// Delegating with no matching agent creates an ephemeral sub-agent with
+// a fresh, isolated context (no builtin tools) and returns its reply.
+func TestDelegateEphemeral(t *testing.T) {
+	fakeGen = func(opts ai.Options, req *ai.Request) (*ai.Response, error) {
+		if strings.Contains(req.SystemPrompt, "sub-agent") {
+			for _, tl := range req.Tools {
+				if tl.Name == toolPlan || tl.Name == toolDelegate {
+					t.Errorf("ephemeral sub-agent must not have builtin tool %q", tl.Name)
+				}
+			}
+			return &ai.Response{Reply: "subtask complete"}, nil
+		}
+		return &ai.Response{Reply: "parent"}, nil
+	}
+	defer func() { fakeGen = nil }()
+
+	a := newTestAgent(Name("root"))
+	content := a.handleDelegate(ai.ToolCall{Name: "delegate", Input: map[string]any{"task": "summarize the report"}}).Content
+	if !strings.Contains(content, "subtask complete") {
+		t.Errorf("delegate should return the sub-agent's reply; got %q", content)
+	}
+}
+
+// Delegating to a name that resolves to a registered agent goes over
+// RPC to that agent rather than spawning a sub-agent.
+func TestDelegateToRegisteredAgent(t *testing.T) {
+	reg := registry.NewMemoryRegistry()
+	if err := reg.Register(&registry.Service{
+		Name:     "comms",
+		Metadata: map[string]string{"type": "agent"},
+		Nodes:    []*registry.Node{{Id: "comms-1", Address: "127.0.0.1:0"}},
+	}); err != nil {
+		t.Fatalf("register agent: %v", err)
+	}
+
+	var calledService, calledEndpoint string
+	fc := &fakeClient{Client: client.DefaultClient}
+	fc.callFn = func(ctx context.Context, req client.Request, rsp interface{}) error {
+		calledService, calledEndpoint = req.Service(), req.Endpoint()
+		frame := rsp.(*codecBytes.Frame)
+		frame.Data = []byte(`{"reply":"notified alice","agent":"comms"}`)
+		return nil
+	}
+
+	// fakeGen guards against the ephemeral path being taken by mistake.
+	fakeGen = func(opts ai.Options, req *ai.Request) (*ai.Response, error) {
+		t.Error("delegate to a registered agent must not spawn a sub-agent")
+		return &ai.Response{}, nil
+	}
+	defer func() { fakeGen = nil }()
+
+	a := newTestAgent(Name("root"), WithRegistry(reg), WithClient(fc))
+	content := a.handleDelegate(ai.ToolCall{Name: "delegate", Input: map[string]any{"task": "notify alice", "to": "comms"}}).Content
+
+	if calledService != "comms" || calledEndpoint != "Agent.Chat" {
+		t.Errorf("expected RPC to comms Agent.Chat, got %s %s", calledService, calledEndpoint)
+	}
+	if !strings.Contains(content, "notified alice") {
+		t.Errorf("delegate-first result missing agent reply; got %q", content)
+	}
+}
+
+// Delegate requires a task.
+func TestDelegateRequiresTask(t *testing.T) {
+	a := newTestAgent(Name("root"))
+	content := a.handleDelegate(ai.ToolCall{Name: "delegate", Input: map[string]any{}}).Content
+	if !strings.Contains(content, "error") {
+		t.Errorf("delegate with no task should error; got %q", content)
+	}
+}

agent/loop_test.go

@@ -0,0 +1,71 @@
+package agent
+
+import (
+	"strings"
+	"testing"
+)
+
+// Repeating the same tool call with the same arguments is refused once it
+// exceeds LoopLimit, and the model is told to change approach.
+func TestLoopDetectionStopsRepeats(t *testing.T) {
+	a := newTestAgent(Name("looper"), LoopLimit(3))
+	h := a.toolHandler()
+
+	// First 3 identical calls are allowed (they fall through to RPC,
+	// which fails harmlessly — we only care they weren't refused as loops).
+	for i := 1; i <= 3; i++ {
+		content := toolContent(h, "demo_Svc_Do", map[string]any{"q": "x"})
+		if strings.Contains(content, "loop detected") {
+			t.Fatalf("call %d wrongly flagged as a loop", i)
+		}
+	}
+
+	// The 4th identical call is refused as a loop.
+	content := toolContent(h, "demo_Svc_Do", map[string]any{"q": "x"})
+	if !strings.Contains(content, "loop detected") {
+		t.Errorf("4th identical call should be refused as a loop; got %q", content)
+	}
+}
+
+// Different arguments are not a loop, even past the limit.
+func TestLoopDetectionAllowsDistinctCalls(t *testing.T) {
+	a := newTestAgent(Name("distinct"), LoopLimit(2))
+	h := a.toolHandler()
+
+	for i := 0; i < 5; i++ {
+		content := toolContent(h, "demo_Svc_Do", map[string]any{"q": i}) // distinct args each time
+		if strings.Contains(content, "loop detected") {
+			t.Fatalf("distinct call %d wrongly flagged as a loop", i)
+		}
+	}
+}
+
+// LoopLimit(0) disables detection.
+func TestLoopDetectionDisabled(t *testing.T) {
+	a := newTestAgent(Name("noloop"), LoopLimit(0))
+	h := a.toolHandler()
+	for i := 0; i < 6; i++ {
+		content := toolContent(h, "demo_Svc_Do", map[string]any{"q": "same"})
+		if strings.Contains(content, "loop detected") {
+			t.Fatalf("loop detection should be disabled with LoopLimit(0)")
+		}
+	}
+}
+
+// It defaults on (lenient) so repeated identical calls are caught without
+// any configuration.
+func TestLoopDetectionDefaultOn(t *testing.T) {
+	a := New(Name("d"), Provider("fake")).(*agentImpl)
+	a.setup()
+	if a.opts.LoopLimit <= 0 {
+		t.Fatalf("LoopLimit should default on, got %d", a.opts.LoopLimit)
+	}
+	h := a.toolHandler()
+	var lastContent string
+	for i := 0; i < a.opts.LoopLimit+1; i++ {
+		lastContent = toolContent(h, "demo_Svc_Do", map[string]any{})
+	}
+	if !strings.Contains(lastContent, "loop detected") {
+		t.Errorf("default loop detection should catch repeated calls; got %q", lastContent)
+	}
+}

agent/memory.go

@@ -0,0 +1,98 @@
+package agent
+
+import (
+	"encoding/json"
+	"sync"
+
+	"go-micro.dev/v6/ai"
+	"go-micro.dev/v6/store"
+)
+
+// Memory is an agent's conversation memory. Like the rest of the
+// framework it is pluggable: the default is store-backed and durable
+// across restarts, but any implementation can be supplied with
+// WithMemory — in-process, a database, or a semantic/vector store.
+type Memory interface {
+	// Add appends a message to the conversation.
+	Add(role, content string)
+	// Messages returns the retained conversation, oldest first.
+	Messages() []ai.Message
+	// Clear resets the conversation.
+	Clear()
+}
+
+// NewMemory returns the default store-backed memory: an in-process
+// conversation buffer (truncated to limit) that persists to the store
+// under key, so an agent picks up where it left off after a restart.
+// A nil store or empty key yields non-persistent memory.
+func NewMemory(s store.Store, key string, limit int) Memory {
+	m := &storeMemory{store: s, key: key, hist: ai.NewHistory(limit)}
+	m.load()
+	return m
+}
+
+// NewInMemory returns conversation memory that is not persisted.
+func NewInMemory(limit int) Memory {
+	return &storeMemory{hist: ai.NewHistory(limit)}
+}
+
+// storeMemory is the default Memory: an ai.History buffer optionally
+// persisted to a store.
+type storeMemory struct {
+	mu    sync.Mutex
+	store store.Store
+	key   string
+	hist  *ai.History
+}
+
+func (m *storeMemory) Add(role, content string) {
+	m.mu.Lock()
+	m.hist.Add(role, content)
+	m.mu.Unlock()
+	m.save()
+}
+
+func (m *storeMemory) Messages() []ai.Message {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.hist.Messages()
+}
+
+func (m *storeMemory) Clear() {
+	m.mu.Lock()
+	m.hist.Reset()
+	m.mu.Unlock()
+	m.save()
+}
+
+func (m *storeMemory) load() {
+	if m.store == nil || m.key == "" {
+		return
+	}
+	recs, err := m.store.Read(m.key)
+	if err != nil || len(recs) == 0 {
+		return
+	}
+	var msgs []ai.Message
+	if err := json.Unmarshal(recs[0].Value, &msgs); err != nil {
+		return
+	}
+	m.mu.Lock()
+	for _, msg := range msgs {
+		m.hist.Add(msg.Role, msg.Content)
+	}
+	m.mu.Unlock()
+}
+
+func (m *storeMemory) save() {
+	if m.store == nil || m.key == "" {
+		return
+	}
+	m.mu.Lock()
+	data, err := json.Marshal(m.hist.Messages())
+	m.mu.Unlock()
+	if err != nil {
+		return
+	}
+	_ = m.store.Write(&store.Record{Key: m.key, Value: data})
+}

agent/memory_test.go

@@ -0,0 +1,114 @@
+package agent
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"go-micro.dev/v6/registry"
+	"go-micro.dev/v6/store"
+)
+
+func TestStoreMemoryPersists(t *testing.T) {
+	st := store.NewMemoryStore()
+	m := NewMemory(st, "agent/x/history", 10)
+	m.Add("user", "hello")
+	m.Add("assistant", "hi there")
+
+	// A fresh memory over the same store/key restores the conversation.
+	reloaded := NewMemory(st, "agent/x/history", 10)
+	if got := len(reloaded.Messages()); got != 2 {
+		t.Fatalf("restored %d messages, want 2", got)
+	}
+}
+
+func TestInMemoryNotPersisted(t *testing.T) {
+	m := NewInMemory(10)
+	m.Add("user", "x")
+	if got := len(m.Messages()); got != 1 {
+		t.Fatalf("got %d messages, want 1", got)
+	}
+	if got := len(NewInMemory(10).Messages()); got != 0 {
+		t.Errorf("a separate in-memory should be empty, got %d", got)
+	}
+}
+
+func TestMemoryClearPersists(t *testing.T) {
+	st := store.NewMemoryStore()
+	m := NewMemory(st, "agent/y/history", 10)
+	m.Add("user", "x")
+	m.Clear()
+	if got := len(m.Messages()); got != 0 {
+		t.Errorf("after Clear got %d messages, want 0", got)
+	}
+	if got := len(NewMemory(st, "agent/y/history", 10).Messages()); got != 0 {
+		t.Errorf("cleared state should persist, reload got %d", got)
+	}
+}
+
+func TestWithMemoryUsed(t *testing.T) {
+	custom := NewInMemory(5)
+	a := New(
+		Name("z"),
+		Provider("fake"),
+		WithRegistry(registry.NewMemoryRegistry()),
+		WithStore(store.NewMemoryStore()),
+		WithMemory(custom),
+	).(*agentImpl)
+	a.setup()
+	if a.mem != custom {
+		t.Error("WithMemory should make the agent use the supplied memory")
+	}
+}
+
+// A custom tool is offered to the model and dispatched to its handler.
+func TestWithToolExposedAndDispatched(t *testing.T) {
+	var got map[string]any
+	a := newTestAgent(Name("calc-agent"),
+		WithTool("calc", "adds two numbers",
+			map[string]any{
+				"a": map[string]any{"type": "number"},
+				"b": map[string]any{"type": "number"},
+			},
+			func(ctx context.Context, input map[string]any) (string, error) {
+				got = input
+				return `{"sum":3}`, nil
+			}))
+
+	tools, err := a.discoverTools()
+	if err != nil {
+		t.Fatalf("discoverTools: %v", err)
+	}
+	found := false
+	for _, tl := range tools {
+		if tl.Name == "calc" {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatal("custom tool 'calc' was not offered to the model")
+	}
+
+	content := toolContent(a.toolHandler(), "calc", map[string]any{"a": 1.0, "b": 2.0})
+	if got == nil {
+		t.Fatal("custom tool handler was not called")
+	}
+	if !strings.Contains(content, "sum") {
+		t.Errorf("custom tool result not returned: %q", content)
+	}
+}
+
+// A custom tool returning an error surfaces it to the model.
+func TestWithToolError(t *testing.T) {
+	a := newTestAgent(Name("err-agent"),
+		WithTool("boom", "always fails", nil,
+			func(ctx context.Context, input map[string]any) (string, error) {
+				return "", errors.New("kaboom")
+			}))
+
+	content := toolContent(a.toolHandler(), "boom", nil)
+	if !strings.Contains(content, "kaboom") {
+		t.Errorf("tool error not surfaced: %q", content)
+	}
+}

agent/options.go

@@ -0,0 +1,210 @@
+package agent
+
+import (
+	"context"
+
+	"go-micro.dev/v6/ai"
+	"go-micro.dev/v6/client"
+	"go-micro.dev/v6/registry"
+	"go-micro.dev/v6/store"
+)
+
+// Option configures an Agent.
+type Option func(*Options)
+
+// ApproveFunc decides whether an agent may execute a tool call before it
+// runs. Returning false blocks the call; the reason is shown to the
+// model so it can adapt. Use it for human-in-the-loop approval or policy
+// checks. It is called for actions (service tools and delegate), not for
+// the internal plan tool.
+type ApproveFunc func(tool string, input map[string]any) (approved bool, reason string)
+
+// ToolFunc handles a custom tool call. Return the result as a string
+// (often JSON); return an error to report failure back to the model.
+type ToolFunc func(ctx context.Context, input map[string]any) (string, error)
+
+// customTool is a developer-registered tool beyond the agent's services.
+type customTool struct {
+	def     ai.Tool
+	handler ToolFunc
+}
+
+// Options holds agent configuration.
+type Options struct {
+	Name         string
+	Services     []string
+	Prompt       string
+	Provider     string
+	Model        string
+	APIKey       string
+	Registry     registry.Registry
+	Client       client.Client
+	Store        store.Store
+	HistoryLimit int
+
+	// Memory is the agent's conversation memory. Nil = the default
+	// store-backed memory (durable across restarts).
+	Memory Memory
+
+	// MaxSteps bounds the number of tool executions per Ask (0 =
+	// unbounded). Once exceeded, further tool calls are refused and the
+	// model is told to stop and summarize. A stopping condition.
+	MaxSteps int
+	// LoopLimit bounds how many times the agent may call the same tool
+	// with the same arguments in one Ask before the call is refused as a
+	// no-progress loop (0 = disabled). Catches the agent repeating an
+	// identical action — which MaxSteps only bounds by total count.
+	LoopLimit int
+	// Approve gates each action before it runs. Nil = allow all.
+	Approve ApproveFunc
+
+	// A2AAddress, if set, makes Run serve this agent over the A2A protocol
+	// on that address directly (no separate gateway), e.g. ":4000".
+	A2AAddress string
+
+	// tools are developer-registered custom tools (see WithTool).
+	tools []customTool
+	// wrappers are developer-registered tool-execution wrappers
+	// (see WrapTool), applied outside the built-in guardrails.
+	wrappers []ai.ToolWrapper
+}
+
+func newOptions(opts ...Option) Options {
+	o := Options{
+		Registry:     registry.DefaultRegistry,
+		Client:       client.DefaultClient,
+		Store:        store.DefaultStore,
+		HistoryLimit: 50,
+		// On by default and lenient: identical repeated calls are a
+		// no-progress loop, never useful. Set LoopLimit(0) to disable.
+		LoopLimit: 3,
+	}
+	for _, opt := range opts {
+		opt(&o)
+	}
+	return o
+}
+
+// Name sets the agent name.
+func Name(n string) Option {
+	return func(o *Options) { o.Name = n }
+}
+
+// Services sets which services this agent manages.
+func Services(names ...string) Option {
+	return func(o *Options) { o.Services = names }
+}
+
+// Prompt sets the system prompt.
+func Prompt(p string) Option {
+	return func(o *Options) { o.Prompt = p }
+}
+
+// Provider sets the LLM provider.
+func Provider(p string) Option {
+	return func(o *Options) { o.Provider = p }
+}
+
+// Model sets the LLM model name.
+func Model(m string) Option {
+	return func(o *Options) { o.Model = m }
+}
+
+// APIKey sets the API key for the LLM provider.
+func APIKey(k string) Option {
+	return func(o *Options) { o.APIKey = k }
+}
+
+// WithRegistry sets the service registry.
+func WithRegistry(r registry.Registry) Option {
+	return func(o *Options) { o.Registry = r }
+}
+
+// WithClient sets the RPC client.
+func WithClient(c client.Client) Option {
+	return func(o *Options) { o.Client = c }
+}
+
+// WithStore sets the store for agent memory.
+func WithStore(s store.Store) Option {
+	return func(o *Options) { o.Store = s }
+}
+
+// HistoryLimit sets the max conversation messages to retain.
+func HistoryLimit(n int) Option {
+	return func(o *Options) { o.HistoryLimit = n }
+}
+
+// MaxSteps bounds tool executions per Ask (0 = unbounded). A stopping
+// condition: beyond the limit, tool calls are refused and the model is
+// told to stop and summarize.
+func MaxSteps(n int) Option {
+	return func(o *Options) { o.MaxSteps = n }
+}
+
+// ApproveTool sets a human-in-the-loop / policy hook called before each
+// action (service tools and delegate). Returning false blocks the call.
+func ApproveTool(fn ApproveFunc) Option {
+	return func(o *Options) { o.Approve = fn }
+}
+
+// LoopLimit sets how many times the agent may repeat the same tool call
+// (same name and arguments) in one Ask before it is refused as a
+// no-progress loop. 0 disables loop detection.
+func LoopLimit(n int) Option {
+	return func(o *Options) { o.LoopLimit = n }
+}
+
+// WithA2A makes Run serve the agent over the A2A protocol on addr (e.g.
+// ":4000"), so other agents can reach it directly by URL without a
+// separate gateway. The agent stays a normal go-micro service as well;
+// this adds a second, A2A-native HTTP endpoint that calls it in-process.
+func WithA2A(addr string) Option {
+	return func(o *Options) { o.A2AAddress = addr }
+}
+
+// WithMemory sets the agent's conversation memory. The default is
+// store-backed memory keyed by agent name; supply your own to use an
+// in-process, database, or semantic store.
+func WithMemory(m Memory) Option {
+	return func(o *Options) { o.Memory = m }
+}
+
+// WrapTool registers a tool-execution wrapper, the tool-side analog of
+// a client/server middleware wrapper. Each wrapper takes the next handler
+// and returns a new one; code before the next(...) call runs before the
+// tool executes, code after runs after. Use it for logging, metrics,
+// retries, or custom policy. Wrappers run outside the built-in guardrails
+// (MaxSteps, LoopLimit, ApproveTool), so they observe every call and its
+// result, including refusals. Multiple wrappers compose outermost-first.
+//
+//	micro.NewAgent("worker", micro.AgentWrapTool(
+//	    func(next ai.ToolHandler) ai.ToolHandler {
+//	        return func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
+//	            res := next(ctx, call)
+//	            log.Printf("id=%s tool=%s", call.ID, call.Name)
+//	            return res
+//	        }
+//	    }))
+func WrapTool(w ...ai.ToolWrapper) Option {
+	return func(o *Options) {
+		o.wrappers = append(o.wrappers, w...)
+	}
+}
+
+// WithTool registers a custom tool the agent can call, beyond the
+// services it discovers — a local function, an external API, anything.
+// properties is the JSON-schema map for the tool's parameters.
+func WithTool(name, description string, properties map[string]any, handler ToolFunc) Option {
+	return func(o *Options) {
+		o.tools = append(o.tools, customTool{
+			def: ai.Tool{
+				Name:         name,
+				OriginalName: name,
+				Description:  description,
+				Properties:   properties,
+			},
+			handler: handler,
+		})
+	}
+}

agent/proto/agent.pb.go

@@ -0,0 +1,267 @@
+// Code generated by protoc-gen-go. DO NOT EDIT.
+// versions:
+// 	protoc-gen-go v1.36.11
+// 	protoc        v3.21.12
+// source: proto/agent.proto
+
+package agent
+
+import (
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
+	reflect "reflect"
+	sync "sync"
+	unsafe "unsafe"
+)
+
+const (
+	// Verify that this generated code is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion)
+	// Verify that runtime/protoimpl is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
+)
+
+type ChatRequest struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Message       string                 `protobuf:"bytes,1,opt,name=message,proto3" json:"message,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ChatRequest) Reset() {
+	*x = ChatRequest{}
+	mi := &file_proto_agent_proto_msgTypes[0]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ChatRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ChatRequest) ProtoMessage() {}
+
+func (x *ChatRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_proto_agent_proto_msgTypes[0]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ChatRequest.ProtoReflect.Descriptor instead.
+func (*ChatRequest) Descriptor() ([]byte, []int) {
+	return file_proto_agent_proto_rawDescGZIP(), []int{0}
+}
+
+func (x *ChatRequest) GetMessage() string {
+	if x != nil {
+		return x.Message
+	}
+	return ""
+}
+
+type ChatResponse struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Reply         string                 `protobuf:"bytes,1,opt,name=reply,proto3" json:"reply,omitempty"`
+	Agent         string                 `protobuf:"bytes,2,opt,name=agent,proto3" json:"agent,omitempty"`
+	ToolCalls     []*ToolCall            `protobuf:"bytes,3,rep,name=tool_calls,json=toolCalls,proto3" json:"tool_calls,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ChatResponse) Reset() {
+	*x = ChatResponse{}
+	mi := &file_proto_agent_proto_msgTypes[1]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ChatResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ChatResponse) ProtoMessage() {}
+
+func (x *ChatResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_proto_agent_proto_msgTypes[1]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ChatResponse.ProtoReflect.Descriptor instead.
+func (*ChatResponse) Descriptor() ([]byte, []int) {
+	return file_proto_agent_proto_rawDescGZIP(), []int{1}
+}
+
+func (x *ChatResponse) GetReply() string {
+	if x != nil {
+		return x.Reply
+	}
+	return ""
+}
+
+func (x *ChatResponse) GetAgent() string {
+	if x != nil {
+		return x.Agent
+	}
+	return ""
+}
+
+func (x *ChatResponse) GetToolCalls() []*ToolCall {
+	if x != nil {
+		return x.ToolCalls
+	}
+	return nil
+}
+
+type ToolCall struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Id            string                 `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
+	Name          string                 `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
+	Input         string                 `protobuf:"bytes,3,opt,name=input,proto3" json:"input,omitempty"`
+	Result        string                 `protobuf:"bytes,4,opt,name=result,proto3" json:"result,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ToolCall) Reset() {
+	*x = ToolCall{}
+	mi := &file_proto_agent_proto_msgTypes[2]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ToolCall) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ToolCall) ProtoMessage() {}
+
+func (x *ToolCall) ProtoReflect() protoreflect.Message {
+	mi := &file_proto_agent_proto_msgTypes[2]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ToolCall.ProtoReflect.Descriptor instead.
+func (*ToolCall) Descriptor() ([]byte, []int) {
+	return file_proto_agent_proto_rawDescGZIP(), []int{2}
+}
+
+func (x *ToolCall) GetId() string {
+	if x != nil {
+		return x.Id
+	}
+	return ""
+}
+
+func (x *ToolCall) GetName() string {
+	if x != nil {
+		return x.Name
+	}
+	return ""
+}
+
+func (x *ToolCall) GetInput() string {
+	if x != nil {
+		return x.Input
+	}
+	return ""
+}
+
+func (x *ToolCall) GetResult() string {
+	if x != nil {
+		return x.Result
+	}
+	return ""
+}
+
+var File_proto_agent_proto protoreflect.FileDescriptor
+
+const file_proto_agent_proto_rawDesc = "" +
+	"\n" +
+	"\x11proto/agent.proto\x12\x05agent\"'\n" +
+	"\vChatRequest\x12\x18\n" +
+	"\amessage\x18\x01 \x01(\tR\amessage\"j\n" +
+	"\fChatResponse\x12\x14\n" +
+	"\x05reply\x18\x01 \x01(\tR\x05reply\x12\x14\n" +
+	"\x05agent\x18\x02 \x01(\tR\x05agent\x12.\n" +
+	"\n" +
+	"tool_calls\x18\x03 \x03(\v2\x0f.agent.ToolCallR\ttoolCalls\"\\\n" +
+	"\bToolCall\x12\x0e\n" +
+	"\x02id\x18\x01 \x01(\tR\x02id\x12\x12\n" +
+	"\x04name\x18\x02 \x01(\tR\x04name\x12\x14\n" +
+	"\x05input\x18\x03 \x01(\tR\x05input\x12\x16\n" +
+	"\x06result\x18\x04 \x01(\tR\x06result2:\n" +
+	"\x05Agent\x121\n" +
+	"\x04Chat\x12\x12.agent.ChatRequest\x1a\x13.agent.ChatResponse\"\x00B\x0fZ\r./proto;agentb\x06proto3"
+
+var (
+	file_proto_agent_proto_rawDescOnce sync.Once
+	file_proto_agent_proto_rawDescData []byte
+)
+
+func file_proto_agent_proto_rawDescGZIP() []byte {
+	file_proto_agent_proto_rawDescOnce.Do(func() {
+		file_proto_agent_proto_rawDescData = protoimpl.X.CompressGZIP(unsafe.Slice(unsafe.StringData(file_proto_agent_proto_rawDesc), len(file_proto_agent_proto_rawDesc)))
+	})
+	return file_proto_agent_proto_rawDescData
+}
+
+var file_proto_agent_proto_msgTypes = make([]protoimpl.MessageInfo, 3)
+var file_proto_agent_proto_goTypes = []any{
+	(*ChatRequest)(nil),  // 0: agent.ChatRequest
+	(*ChatResponse)(nil), // 1: agent.ChatResponse
+	(*ToolCall)(nil),     // 2: agent.ToolCall
+}
+var file_proto_agent_proto_depIdxs = []int32{
+	2, // 0: agent.ChatResponse.tool_calls:type_name -> agent.ToolCall
+	0, // 1: agent.Agent.Chat:input_type -> agent.ChatRequest
+	1, // 2: agent.Agent.Chat:output_type -> agent.ChatResponse
+	2, // [2:3] is the sub-list for method output_type
+	1, // [1:2] is the sub-list for method input_type
+	1, // [1:1] is the sub-list for extension type_name
+	1, // [1:1] is the sub-list for extension extendee
+	0, // [0:1] is the sub-list for field type_name
+}
+
+func init() { file_proto_agent_proto_init() }
+func file_proto_agent_proto_init() {
+	if File_proto_agent_proto != nil {
+		return
+	}
+	type x struct{}
+	out := protoimpl.TypeBuilder{
+		File: protoimpl.DescBuilder{
+			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
+			RawDescriptor: unsafe.Slice(unsafe.StringData(file_proto_agent_proto_rawDesc), len(file_proto_agent_proto_rawDesc)),
+			NumEnums:      0,
+			NumMessages:   3,
+			NumExtensions: 0,
+			NumServices:   1,
+		},
+		GoTypes:           file_proto_agent_proto_goTypes,
+		DependencyIndexes: file_proto_agent_proto_depIdxs,
+		MessageInfos:      file_proto_agent_proto_msgTypes,
+	}.Build()
+	File_proto_agent_proto = out.File
+	file_proto_agent_proto_goTypes = nil
+	file_proto_agent_proto_depIdxs = nil
+}

agent/proto/agent.pb.micro.go

@@ -0,0 +1,79 @@
+// Code generated by protoc-gen-micro. DO NOT EDIT.
+// source: proto/agent.proto
+
+package agent
+
+import (
+	fmt "fmt"
+	proto "google.golang.org/protobuf/proto"
+	math "math"
+)
+
+import (
+	context "context"
+	client "go-micro.dev/v6/client"
+	server "go-micro.dev/v6/server"
+)
+
+// Reference imports to suppress errors if they are not otherwise used.
+var _ = proto.Marshal
+var _ = fmt.Errorf
+var _ = math.Inf
+
+// Reference imports to suppress errors if they are not otherwise used.
+var _ context.Context
+var _ client.Option
+var _ server.Option
+
+// Client API for Agent service
+
+type AgentService interface {
+	Chat(ctx context.Context, in *ChatRequest, opts ...client.CallOption) (*ChatResponse, error)
+}
+
+type agentService struct {
+	c    client.Client
+	name string
+}
+
+func NewAgentService(name string, c client.Client) AgentService {
+	return &agentService{
+		c:    c,
+		name: name,
+	}
+}
+
+func (c *agentService) Chat(ctx context.Context, in *ChatRequest, opts ...client.CallOption) (*ChatResponse, error) {
+	req := c.c.NewRequest(c.name, "Agent.Chat", in)
+	out := new(ChatResponse)
+	err := c.c.Call(ctx, req, out, opts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// Server API for Agent service
+
+type AgentHandler interface {
+	Chat(context.Context, *ChatRequest, *ChatResponse) error
+}
+
+func RegisterAgentHandler(s server.Server, hdlr AgentHandler, opts ...server.HandlerOption) error {
+	type agent interface {
+		Chat(ctx context.Context, in *ChatRequest, out *ChatResponse) error
+	}
+	type Agent struct {
+		agent
+	}
+	h := &agentHandler{hdlr}
+	return s.Handle(s.NewHandler(&Agent{h}, opts...))
+}
+
+type agentHandler struct {
+	AgentHandler
+}
+
+func (h *agentHandler) Chat(ctx context.Context, in *ChatRequest, out *ChatResponse) error {
+	return h.AgentHandler.Chat(ctx, in, out)
+}

agent/proto/agent.proto

@@ -0,0 +1,27 @@
+syntax = "proto3";
+
+package agent;
+
+option go_package = "./proto;agent";
+
+// Agent is the RPC interface for an AI agent.
+service Agent {
+	rpc Chat(ChatRequest) returns (ChatResponse) {}
+}
+
+message ChatRequest {
+	string message = 1;
+}
+
+message ChatResponse {
+	string reply = 1;
+	string agent = 2;
+	repeated ToolCall tool_calls = 3;
+}
+
+message ToolCall {
+	string id = 1;
+	string name = 2;
+	string input = 3;
+	string result = 4;
+}

agent/wrap_test.go

@@ -0,0 +1,176 @@
+package agent
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+
+	"go-micro.dev/v6/ai"
+	"go-micro.dev/v6/registry"
+	"go-micro.dev/v6/store"
+)
+
+// A registered wrapper runs around every tool call and can observe and
+// modify the result.
+func TestWrapToolWraps(t *testing.T) {
+	var saw string
+	wrap := func(next ai.ToolHandler) ai.ToolHandler {
+		return func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
+			saw = call.Name
+			res := next(ctx, call)
+			res.Content = "wrapped:" + res.Content
+			return res
+		}
+	}
+
+	a := newTestAgent(Name("wrapped"), WrapTool(wrap))
+	content := toolContent(a.toolHandler(), "demo_Svc_Do", map[string]any{})
+
+	if saw != "demo_Svc_Do" {
+		t.Errorf("wrapper saw %q, want demo_Svc_Do", saw)
+	}
+	if !strings.HasPrefix(content, "wrapped:") {
+		t.Errorf("wrapper did not modify the result; got %q", content)
+	}
+}
+
+// Multiple wrappers compose outermost-first: the first registered wrapper
+// is the outer layer, so it runs first on the way in and last on the way
+// out.
+func TestWrapToolOrder(t *testing.T) {
+	var order []string
+	mk := func(tag string) ai.ToolWrapper {
+		return func(next ai.ToolHandler) ai.ToolHandler {
+			return func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
+				order = append(order, "in:"+tag)
+				res := next(ctx, call)
+				order = append(order, "out:"+tag)
+				return res
+			}
+		}
+	}
+
+	a := newTestAgent(Name("ordered"), WrapTool(mk("a"), mk("b")))
+	toolContent(a.toolHandler(), "demo_Svc_Do", map[string]any{})
+
+	want := "in:a in:b out:b out:a"
+	if got := strings.Join(order, " "); got != want {
+		t.Errorf("wrapper order = %q, want %q", got, want)
+	}
+}
+
+// Wrappers run outside the built-in guardrails, so they observe a refused
+// call and its refusal result rather than being short-circuited.
+func TestWrapToolSeesGuardrailRefusal(t *testing.T) {
+	var sawResult string
+	wrap := func(next ai.ToolHandler) ai.ToolHandler {
+		return func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
+			res := next(ctx, call)
+			sawResult = res.Content
+			return res
+		}
+	}
+
+	a := newTestAgent(Name("gated-wrap"),
+		ApproveTool(func(tool string, input map[string]any) (bool, string) {
+			return false, "denied"
+		}),
+		WrapTool(wrap),
+	)
+	toolContent(a.toolHandler(), "demo_Svc_Do", map[string]any{})
+
+	if !strings.Contains(sawResult, "not approved") {
+		t.Errorf("wrapper should observe the guardrail refusal; got %q", sawResult)
+	}
+}
+
+// A guardrail refusal carries a structured reason a wrapper can switch on,
+// so reliability tooling (e.g. loop handling) needn't parse the message.
+func TestWrapToolSeesRefusedReason(t *testing.T) {
+	a := newTestAgent(Name("looper"), LoopLimit(2))
+	h := a.toolHandler()
+
+	var last ai.ToolResult
+	for i := 0; i < 3; i++ {
+		last = h(context.Background(), ai.ToolCall{ID: "x", Name: "demo_Svc_Do", Input: map[string]any{"q": "same"}})
+	}
+	if last.Refused != ai.RefusedLoop {
+		t.Errorf("Refused = %q, want %q", last.Refused, ai.RefusedLoop)
+	}
+}
+
+// ctxMock is a model that forwards the Generate context to the tool
+// handler (as real providers do), so a wrapper can read ai.RunInfo.
+type ctxMock struct{ opts ai.Options }
+
+func (m *ctxMock) Init(opts ...ai.Option) error {
+	for _, o := range opts {
+		o(&m.opts)
+	}
+	return nil
+}
+func (m *ctxMock) Options() ai.Options { return m.opts }
+func (m *ctxMock) String() string      { return "ctxmock" }
+func (m *ctxMock) Stream(context.Context, *ai.Request, ...ai.GenerateOption) (ai.Stream, error) {
+	return nil, fmt.Errorf("no stream")
+}
+func (m *ctxMock) Generate(ctx context.Context, _ *ai.Request, _ ...ai.GenerateOption) (*ai.Response, error) {
+	if m.opts.ToolHandler != nil {
+		m.opts.ToolHandler(ctx, ai.ToolCall{ID: "c1", Name: "demo_Svc_Do", Input: map[string]any{}})
+	}
+	return &ai.Response{Answer: "done"}, nil
+}
+
+// During an Ask, a wrapper sees RunInfo on the context: a correlation id
+// for the run and the agent's name.
+func TestWrapToolSeesRunInfo(t *testing.T) {
+	ai.Register("ctxmock", func(opts ...ai.Option) ai.Model {
+		m := &ctxMock{}
+		_ = m.Init(opts...)
+		return m
+	})
+
+	var got ai.RunInfo
+	var ok bool
+	a := New(
+		Name("runner"),
+		Provider("ctxmock"),
+		WithRegistry(registry.NewMemoryRegistry()),
+		WithStore(store.NewMemoryStore()),
+		WrapTool(func(next ai.ToolHandler) ai.ToolHandler {
+			return func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
+				got, ok = ai.RunInfoFrom(ctx)
+				return next(ctx, call)
+			}
+		}),
+	)
+
+	if _, err := a.Ask(context.Background(), "go"); err != nil {
+		t.Fatalf("Ask: %v", err)
+	}
+	if !ok {
+		t.Fatal("wrapper did not see RunInfo on the context")
+	}
+	if got.Agent != "runner" {
+		t.Errorf("RunInfo.Agent = %q, want runner", got.Agent)
+	}
+	if got.RunID == "" {
+		t.Error("RunInfo.RunID is empty")
+	}
+}
+
+// call.Scan decodes a tool call's input into a typed struct.
+func TestToolCallScan(t *testing.T) {
+	call := ai.ToolCall{Input: map[string]any{"query": "hello", "limit": 5}}
+	var args struct {
+		Query string `json:"query"`
+		Limit int    `json:"limit"`
+	}
+	if err := call.Scan(&args); err != nil {
+		t.Fatalf("Scan: %v", err)
+	}
+	if args.Query != "hello" || args.Limit != 5 {
+		t.Errorf("Scan decoded %+v, want {hello 5}", args)
+	}
+}

ai/README.md

@@ -0,0 +1,351 @@
+# AI Package
+
+The `ai` package provides simple, high-level interfaces for AI model providers. It supports text generation (`Model`), image generation (`ImageModel`), and video generation (`VideoModel`).
+
+## Interfaces
+
+### Text Generation (Model)
+
+The Model interface follows the same patterns as other go-micro packages (Registry, Client, Broker):
+
+```go
+type Model interface {
+    Init(...Option) error
+    Options() Options
+    Generate(ctx context.Context, req *Request, opts ...GenerateOption) (*Response, error)
+    Stream(ctx context.Context, req *Request, opts ...GenerateOption) (Stream, error)
+    String() string
+}
+```
+
+## Quick Start
+
+```go
+import (
+    "context"
+    "go-micro.dev/v5/ai"
+    _ "go-micro.dev/v5/ai/anthropic"
+    _ "go-micro.dev/v5/ai/openai"
+)
+
+// Create a model
+m := ai.New("openai",
+    ai.WithAPIKey("your-api-key"),
+    ai.WithModel("gpt-4o"),
+)
+
+// Generate a response
+req := &ai.Request{
+    Prompt:       "What is Go?",
+    SystemPrompt: "You are a helpful programming assistant",
+}
+
+resp, err := m.Generate(context.Background(), req)
+if err != nil {
+    log.Fatal(err)
+}
+
+fmt.Println(resp.Reply)
+```
+
+### Image Generation (ImageModel)
+
+```go
+type ImageModel interface {
+    GenerateImage(ctx context.Context, req *ImageRequest, opts ...GenerateOption) (*ImageResponse, error)
+    String() string
+}
+```
+
+```go
+import (
+    "go-micro.dev/v5/ai"
+    _ "go-micro.dev/v5/ai/atlascloud"
+)
+
+ig := ai.NewImage("atlascloud",
+    ai.WithAPIKey("your-api-key"),
+)
+
+resp, err := ig.GenerateImage(context.Background(), &ai.ImageRequest{
+    Prompt: "A Go gopher in space",
+    Size:   "1024x1024",
+})
+
+fmt.Println(resp.Images[0].URL)
+```
+
+Providers that support image generation: **Atlas Cloud**, **OpenAI**.
+
+### Video Generation (VideoModel)
+
+```go
+type VideoModel interface {
+    GenerateVideo(ctx context.Context, req *VideoRequest, opts ...GenerateOption) (*VideoResponse, error)
+    String() string
+}
+```
+
+```go
+import (
+    "go-micro.dev/v5/ai"
+    _ "go-micro.dev/v5/ai/atlascloud"
+)
+
+vg := ai.NewVideo("atlascloud",
+    ai.WithAPIKey("your-api-key"),
+)
+
+resp, err := vg.GenerateVideo(context.Background(), &ai.VideoRequest{
+    Prompt:   "Microservices nodes animating with data flowing between them",
+    Images:   []string{"https://example.com/diagram.png"}, // optional: image-to-video
+    Duration: 6,
+})
+
+fmt.Println(resp.URL)
+```
+
+Providers that support video generation: **Atlas Cloud**.
+
+## Options
+
+Configure the model using functional options:
+
+```go
+m := ai.New("anthropic",
+    ai.WithAPIKey("your-key"),              // Required
+    ai.WithModel("claude-sonnet-4-20250514"), // Optional, uses provider default
+    ai.WithBaseURL("https://api.anthropic.com"), // Optional, uses provider default
+)
+```
+
+You can also update options after creation:
+
+```go
+m.Init(
+    ai.WithModel("gpt-4o-mini"),
+    ai.WithAPIKey("new-key"),
+)
+```
+
+## Using Tools
+
+The model can automatically execute tool calls when provided with a tool handler:
+
+```go
+// Define a tool handler. It mirrors a go-micro RPC handler: context
+// first, the call in, a result out.
+toolHandler := func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
+    // Execute the tool and return results
+    switch call.Name {
+    case "get_weather":
+        return ai.ToolResult{ID: call.ID, Value: map[string]string{"temp": "72F"}, Content: `{"temp": "72F"}`}
+    default:
+        return ai.ToolResult{ID: call.ID, Content: `{"error": "unknown tool"}`}
+    }
+}
+
+// Create model with tool handler
+m := ai.New("openai",
+    ai.WithAPIKey("your-key"),
+    ai.WithToolHandler(toolHandler),
+)
+
+// Provide tools in the request
+req := &ai.Request{
+    Prompt: "What's the weather?",
+    SystemPrompt: "You are a helpful assistant",
+    Tools: []ai.Tool{
+        {
+            Name:        "get_weather",
+            Description: "Get current weather",
+            Properties: map[string]any{
+                "location": map[string]any{
+                    "type": "string",
+                    "description": "City name",
+                },
+            },
+        },
+    },
+}
+
+// Generate will automatically call tools and return final answer
+resp, err := m.Generate(context.Background(), req)
+fmt.Println(resp.Answer) // Final answer after tool execution
+```
+
+## Response Structure
+
+```go
+type Response struct {
+    Reply     string      // Initial reply from model
+    ToolCalls []ToolCall  // Tools the model wants to call
+    Answer    string      // Final answer (after tool execution if handler provided)
+}
+```
+
+- `Reply`: The model's first response
+- `ToolCalls`: List of tools the model requested (if any)
+- `Answer`: The final answer after tools are executed (only set if ToolHandler is provided)
+
+## Supported Providers
+
+### Anthropic Claude
+
+```go
+m := ai.New("anthropic",
+    ai.WithAPIKey("sk-ant-..."),
+    ai.WithModel("claude-sonnet-4-20250514"), // default
+)
+```
+
+Default model: `claude-sonnet-4-20250514`
+Default base URL: `https://api.anthropic.com`
+
+### OpenAI GPT
+
+```go
+m := ai.New("openai",
+    ai.WithAPIKey("sk-..."),
+    ai.WithModel("gpt-4o"), // default
+)
+```
+
+Default model: `gpt-4o`
+Default base URL: `https://api.openai.com`
+
+### Google Gemini
+
+```go
+m := ai.New("gemini",
+    ai.WithAPIKey("your-key"),
+    ai.WithModel("gemini-2.5-flash"), // default
+)
+```
+
+Default model: `gemini-2.5-flash`
+Default base URL: `https://generativelanguage.googleapis.com`
+
+Google Gemini uses its own API format with `system_instruction`, `contents` (not `messages`), and `functionDeclarations` for tool calling. The provider handles the translation automatically.
+
+### Groq
+
+```go
+m := ai.New("groq",
+    ai.WithAPIKey("your-key"),
+    ai.WithModel("llama-3.3-70b-versatile"), // default
+)
+```
+
+Default model: `llama-3.3-70b-versatile`
+Default base URL: `https://api.groq.com/openai`
+
+Groq provides ultra-fast inference for open-weight models via an OpenAI-compatible endpoint.
+
+### Mistral
+
+```go
+m := ai.New("mistral",
+    ai.WithAPIKey("your-key"),
+    ai.WithModel("mistral-large-latest"), // default
+)
+```
+
+Default model: `mistral-large-latest`
+Default base URL: `https://api.mistral.ai`
+
+Mistral AI is a European AI company offering high-performance models via an OpenAI-compatible endpoint.
+
+### Together AI
+
+```go
+m := ai.New("together",
+    ai.WithAPIKey("your-key"),
+    ai.WithModel("meta-llama/Llama-3.3-70B-Instruct-Turbo"), // default
+)
+```
+
+Default model: `meta-llama/Llama-3.3-70B-Instruct-Turbo`
+Default base URL: `https://api.together.xyz`
+
+Together AI provides fast inference for open-weight models via an OpenAI-compatible endpoint.
+
+### Atlas Cloud
+
+```go
+m := ai.New("atlascloud",
+    ai.WithAPIKey("your-key"),
+    ai.WithModel("llama-3.3-70b"), // default
+)
+```
+
+Default model: `llama-3.3-70b`
+Default base URL: `https://api.atlascloud.ai`
+
+Atlas Cloud is an enterprise AI infrastructure platform offering high-performance LLM APIs. It exposes an OpenAI-compatible chat completions endpoint with tool calling support.
+
+## Auto-Detection
+
+Use `AutoDetectProvider()` to detect the provider from a base URL:
+
+```go
+provider := ai.AutoDetectProvider("https://api.anthropic.com")
+// Returns "anthropic"
+
+m := ai.New(provider, ai.WithAPIKey("..."))
+```
+
+## Adding a New Provider
+
+See the full **[AI Provider Integration Guide](../internal/website/docs/guides/ai-provider-guide.md)** for a step-by-step walkthrough, checklist, and design notes.
+
+Quick summary:
+
+1. Create `ai/yourprovider/yourprovider.go` implementing `ai.Model`.
+2. Call `ai.Register("yourprovider", ...)` in `init()`.
+3. Add tests in `ai/yourprovider/yourprovider_test.go`.
+4. Users enable the provider with a blank import:
+
+```go
+import _ "go-micro.dev/v5/ai/yourprovider"
+```
+
+We welcome contributions and sponsorships from AI infrastructure companies — see the guide for details.
+
+## Comparison with Other Packages
+
+The ai package follows the same patterns as other go-micro packages:
+
+**Registry:**
+```go
+r := registry.NewRegistry(registry.Addrs("..."))
+r.Register(service)
+```
+
+**Client:**
+```go
+c := client.NewClient(client.Retries(3))
+c.Call(ctx, req, rsp)
+```
+
+**AI:**
+```go
+m := ai.New("openai", ai.WithAPIKey("..."))
+m.Generate(ctx, req)
+```
+
+All use:
+- `Init()` to update options
+- `Options()` to get current options
+- `String()` to get the implementation name
+- Functional options pattern
+
+## Testing
+
+```bash
+go test ./ai/...
+```
+
+## Examples
+
+See the [server implementation](../cmd/micro/server/server.go) for a complete example of using the ai package with tool execution.

ai/anthropic/anthropic.go

@@ -0,0 +1,272 @@
+// Package anthropic implements the Anthropic Claude model provider
+package anthropic
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"go-micro.dev/v6/ai"
+)
+
+func init() {
+	ai.Register("anthropic", func(opts ...ai.Option) ai.Model {
+		return NewProvider(opts...)
+	})
+}
+
+// Provider implements the ai.Model interface for Anthropic Claude
+type Provider struct {
+	opts ai.Options
+}
+
+// NewProvider creates a new Anthropic provider
+func NewProvider(opts ...ai.Option) *Provider {
+	options := ai.NewOptions(opts...)
+
+	// Set defaults if not provided
+	if options.Model == "" {
+		options.Model = "claude-sonnet-4-20250514"
+	}
+	if options.BaseURL == "" {
+		options.BaseURL = "https://api.anthropic.com"
+	}
+
+	return &Provider{
+		opts: options,
+	}
+}
+
+// Init initializes the provider with options
+func (p *Provider) Init(opts ...ai.Option) error {
+	for _, o := range opts {
+		o(&p.opts)
+	}
+	return nil
+}
+
+// Options returns the provider options
+func (p *Provider) Options() ai.Options {
+	return p.opts
+}
+
+// String returns the provider name
+func (p *Provider) String() string {
+	return "anthropic"
+}
+
+// Generate generates a response from the model
+func (p *Provider) Generate(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (*ai.Response, error) {
+	// Build tools for Anthropic format
+	var anthropicTools []map[string]any
+	for _, t := range req.Tools {
+		anthropicTools = append(anthropicTools, map[string]any{
+			"name":        t.Name,
+			"description": t.Description,
+			"input_schema": map[string]any{
+				"type":       "object",
+				"properties": t.Properties,
+			},
+		})
+	}
+
+	// Build initial request
+	apiReq := map[string]any{
+		"model":      p.opts.Model,
+		"max_tokens": 8192,
+		"system":     req.SystemPrompt,
+		"messages": []map[string]any{
+			{"role": "user", "content": req.Prompt},
+		},
+	}
+
+	if len(anthropicTools) > 0 {
+		apiReq["tools"] = anthropicTools
+	}
+
+	// Make API call
+	resp, rawContent, err := p.callAPI(ctx, apiReq)
+	if err != nil {
+		return nil, err
+	}
+
+	// If no tool calls or no handler, return as-is
+	if len(resp.ToolCalls) == 0 || p.opts.ToolHandler == nil {
+		return resp, nil
+	}
+
+	// Tool execution loop: execute tools, send results back, repeat
+	// until the model responds with text only (no more tool calls)
+	messages := []map[string]any{
+		{"role": "user", "content": req.Prompt},
+		{"role": "assistant", "content": cleanContent(rawContent)},
+	}
+
+	pendingCalls := resp.ToolCalls
+
+	for rounds := 0; rounds < 10; rounds++ {
+		var toolResultBlocks []map[string]any
+		for i := range pendingCalls {
+			content := p.opts.ToolHandler(ctx, pendingCalls[i]).Content
+			pendingCalls[i].Result = content
+			toolResultBlocks = append(toolResultBlocks, map[string]any{
+				"type":        "tool_result",
+				"tool_use_id": pendingCalls[i].ID,
+				"content":     content,
+			})
+		}
+
+		messages = append(messages, map[string]any{
+			"role":    "user",
+			"content": toolResultBlocks,
+		})
+
+		followUpReq := map[string]any{
+			"model":      p.opts.Model,
+			"max_tokens": 8192,
+			"system":     req.SystemPrompt,
+			"messages":   messages,
+		}
+		if len(anthropicTools) > 0 {
+			followUpReq["tools"] = anthropicTools
+		}
+
+		followUpResp, followUpRaw, err := p.callAPI(ctx, followUpReq)
+		if err != nil {
+			break
+		}
+
+		if len(followUpResp.ToolCalls) > 0 {
+			resp.ToolCalls = append(resp.ToolCalls, followUpResp.ToolCalls...)
+			pendingCalls = followUpResp.ToolCalls
+			messages = append(messages, map[string]any{
+				"role":    "assistant",
+				"content": cleanContent(followUpRaw),
+			})
+			continue
+		}
+
+		if followUpResp.Reply != "" {
+			resp.Answer = followUpResp.Reply
+		}
+		break
+	}
+
+	return resp, nil
+}
+
+// Stream generates a streaming response (not yet implemented)
+func (p *Provider) Stream(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (ai.Stream, error) {
+	return nil, fmt.Errorf("streaming not yet implemented for anthropic provider")
+}
+
+// callAPI makes an HTTP request to the Anthropic API
+func (p *Provider) callAPI(ctx context.Context, req map[string]any) (*ai.Response, any, error) {
+	// Marshal request
+	reqBody, err := json.Marshal(req)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	// Build HTTP request
+	apiURL := strings.TrimRight(p.opts.BaseURL, "/") + "/v1/messages"
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, bytes.NewReader(reqBody))
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	// Set headers
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("x-api-key", p.opts.APIKey)
+	httpReq.Header.Set("anthropic-version", "2023-06-01")
+
+	// Make request
+	httpResp, err := http.DefaultClient.Do(httpReq)
+	if err != nil {
+		return nil, nil, fmt.Errorf("API request failed: %w", err)
+	}
+	defer httpResp.Body.Close()
+
+	// Read response
+	respBody, _ := io.ReadAll(httpResp.Body)
+	if httpResp.StatusCode != http.StatusOK {
+		return nil, nil, fmt.Errorf("API error (%s): %s", httpResp.Status, string(respBody))
+	}
+
+	// Parse response
+	var anthropicResp struct {
+		Content []struct {
+			Type  string          `json:"type"`
+			Text  string          `json:"text"`
+			ID    string          `json:"id"`
+			Name  string          `json:"name"`
+			Input json.RawMessage `json:"input"`
+		} `json:"content"`
+		StopReason string `json:"stop_reason"`
+	}
+
+	if err := json.Unmarshal(respBody, &anthropicResp); err != nil {
+		return nil, nil, fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	response := &ai.Response{}
+
+	// Extract text reply
+	var replyParts []string
+	for _, block := range anthropicResp.Content {
+		if block.Type == "text" && block.Text != "" {
+			replyParts = append(replyParts, block.Text)
+		}
+	}
+	if len(replyParts) > 0 {
+		response.Reply = strings.Join(replyParts, "\n")
+	}
+
+	// Extract tool calls
+	for _, block := range anthropicResp.Content {
+		if block.Type == "tool_use" {
+			var input map[string]any
+			if err := json.Unmarshal(block.Input, &input); err != nil {
+				input = map[string]any{}
+			}
+			response.ToolCalls = append(response.ToolCalls, ai.ToolCall{
+				ID:    block.ID,
+				Name:  block.Name,
+				Input: input,
+			})
+		}
+	}
+
+	return response, anthropicResp.Content, nil
+}
+
+// cleanContent strips fields from response content blocks that Anthropic
+// rejects when sent back as assistant message content (e.g. "id" on text blocks).
+func cleanContent(raw any) any {
+	blocks, ok := raw.([]struct {
+		Type  string          `json:"type"`
+		Text  string          `json:"text"`
+		ID    string          `json:"id"`
+		Name  string          `json:"name"`
+		Input json.RawMessage `json:"input"`
+	})
+	if !ok {
+		return raw
+	}
+	var cleaned []map[string]any
+	for _, b := range blocks {
+		switch b.Type {
+		case "text":
+			cleaned = append(cleaned, map[string]any{"type": "text", "text": b.Text})
+		case "tool_use":
+			var input any
+			_ = json.Unmarshal(b.Input, &input)
+			cleaned = append(cleaned, map[string]any{"type": "tool_use", "id": b.ID, "name": b.Name, "input": input})
+		}
+	}
+	return cleaned
+}

ai/anthropic/anthropic_test.go

@@ -0,0 +1,94 @@
+package anthropic
+
+import (
+	"context"
+	"testing"
+
+	"go-micro.dev/v6/ai"
+)
+
+func TestProvider_String(t *testing.T) {
+	p := NewProvider()
+	if p.String() != "anthropic" {
+		t.Errorf("Expected provider name 'anthropic', got '%s'", p.String())
+	}
+}
+
+func TestProvider_Init(t *testing.T) {
+	p := NewProvider()
+
+	err := p.Init(
+		ai.WithModel("test-model"),
+		ai.WithAPIKey("test-key"),
+		ai.WithBaseURL("https://test.com"),
+	)
+
+	if err != nil {
+		t.Fatalf("Init failed: %v", err)
+	}
+
+	opts := p.Options()
+	if opts.Model != "test-model" {
+		t.Errorf("Expected model 'test-model', got '%s'", opts.Model)
+	}
+	if opts.APIKey != "test-key" {
+		t.Errorf("Expected API key 'test-key', got '%s'", opts.APIKey)
+	}
+	if opts.BaseURL != "https://test.com" {
+		t.Errorf("Expected base URL 'https://test.com', got '%s'", opts.BaseURL)
+	}
+}
+
+func TestProvider_Options(t *testing.T) {
+	p := NewProvider(
+		ai.WithModel("custom-model"),
+		ai.WithAPIKey("my-key"),
+	)
+
+	opts := p.Options()
+	if opts.Model != "custom-model" {
+		t.Errorf("Expected model 'custom-model', got '%s'", opts.Model)
+	}
+	if opts.APIKey != "my-key" {
+		t.Errorf("Expected API key 'my-key', got '%s'", opts.APIKey)
+	}
+}
+
+func TestProvider_Defaults(t *testing.T) {
+	p := NewProvider()
+
+	opts := p.Options()
+	if opts.Model != "claude-sonnet-4-20250514" {
+		t.Errorf("Expected default model 'claude-sonnet-4-20250514', got '%s'", opts.Model)
+	}
+	if opts.BaseURL != "https://api.anthropic.com" {
+		t.Errorf("Expected default base URL 'https://api.anthropic.com', got '%s'", opts.BaseURL)
+	}
+}
+
+func TestProvider_Generate_NoAPIKey(t *testing.T) {
+	p := NewProvider()
+
+	req := &ai.Request{
+		Prompt:       "Hello",
+		SystemPrompt: "You are helpful",
+	}
+
+	_, err := p.Generate(context.Background(), req)
+	if err == nil {
+		t.Error("Expected error when API key is missing, got nil")
+	}
+}
+
+func TestProvider_Stream_NotImplemented(t *testing.T) {
+	p := NewProvider()
+
+	req := &ai.Request{
+		Prompt: "Hello",
+	}
+
+	_, err := p.Stream(context.Background(), req)
+	if err == nil {
+		t.Error("Expected error for unimplemented streaming, got nil")
+	}
+}

ai/atlascloud/atlascloud.go

@@ -0,0 +1,489 @@
+// Package atlascloud implements the Atlas Cloud model provider.
+//
+// Atlas Cloud is an enterprise AI infrastructure platform offering
+// high-performance LLM, image, and video APIs. It exposes
+// OpenAI-compatible endpoints for chat completions and image
+// generation.
+//
+// Usage:
+//
+//	import _ "go-micro.dev/v6/ai/atlascloud"
+//
+//	m := ai.New("atlascloud",
+//	    ai.WithAPIKey("your-api-key"),
+//	)
+//
+//	// Image generation
+//	ig := ai.NewImage("atlascloud",
+//	    ai.WithAPIKey("your-api-key"),
+//	)
+package atlascloud
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"go-micro.dev/v6/ai"
+)
+
+func init() {
+	ai.Register("atlascloud", func(opts ...ai.Option) ai.Model {
+		return NewProvider(opts...)
+	})
+	ai.RegisterImage("atlascloud", func(opts ...ai.Option) ai.ImageModel {
+		return NewProvider(opts...)
+	})
+	ai.RegisterVideo("atlascloud", func(opts ...ai.Option) ai.VideoModel {
+		return NewProvider(opts...)
+	})
+}
+
+// Provider implements the ai.Model interface for Atlas Cloud.
+type Provider struct {
+	opts ai.Options
+}
+
+// NewProvider creates a new Atlas Cloud provider.
+func NewProvider(opts ...ai.Option) *Provider {
+	options := ai.NewOptions(opts...)
+
+	if options.Model == "" {
+		options.Model = "deepseek-ai/DeepSeek-V3-0324"
+	}
+	if options.BaseURL == "" {
+		options.BaseURL = "https://api.atlascloud.ai"
+	}
+
+	return &Provider{opts: options}
+}
+
+func (p *Provider) Init(opts ...ai.Option) error {
+	for _, o := range opts {
+		o(&p.opts)
+	}
+	return nil
+}
+
+func (p *Provider) Options() ai.Options { return p.opts }
+func (p *Provider) String() string      { return "atlascloud" }
+
+func (p *Provider) Generate(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (*ai.Response, error) {
+	var tools []map[string]any
+	for _, t := range req.Tools {
+		tools = append(tools, map[string]any{
+			"type": "function",
+			"function": map[string]any{
+				"name":        t.Name,
+				"description": t.Description,
+				"parameters": map[string]any{
+					"type":       "object",
+					"properties": t.Properties,
+				},
+			},
+		})
+	}
+
+	messages := []map[string]any{
+		{"role": "system", "content": req.SystemPrompt},
+		{"role": "user", "content": req.Prompt},
+	}
+
+	apiReq := map[string]any{
+		"model":    p.opts.Model,
+		"messages": messages,
+	}
+
+	if len(tools) > 0 {
+		apiReq["tools"] = tools
+	}
+
+	resp, rawMessage, err := p.callAPI(ctx, apiReq)
+	if err != nil {
+		return nil, err
+	}
+
+	if len(resp.ToolCalls) == 0 {
+		return resp, nil
+	}
+
+	if p.opts.ToolHandler != nil {
+		followUpMessages := append(messages, map[string]any{
+			"role":       "assistant",
+			"content":    rawMessage["content"],
+			"tool_calls": rawMessage["tool_calls"],
+		})
+
+		for _, tc := range resp.ToolCalls {
+			content := p.opts.ToolHandler(ctx, tc).Content
+			followUpMessages = append(followUpMessages, map[string]any{
+				"role":         "tool",
+				"tool_call_id": tc.ID,
+				"content":      content,
+			})
+		}
+
+		followUpReq := map[string]any{
+			"model":    p.opts.Model,
+			"messages": followUpMessages,
+		}
+
+		followUpResp, _, err := p.callAPI(ctx, followUpReq)
+		if err == nil && followUpResp.Reply != "" {
+			resp.Answer = followUpResp.Reply
+		}
+	}
+
+	return resp, nil
+}
+
+func (p *Provider) Stream(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (ai.Stream, error) {
+	return nil, fmt.Errorf("streaming not yet implemented for atlascloud provider")
+}
+
+func (p *Provider) callAPI(ctx context.Context, req map[string]any) (*ai.Response, map[string]any, error) {
+	reqBody, err := json.Marshal(req)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	apiURL := strings.TrimRight(p.opts.BaseURL, "/") + "/v1/chat/completions"
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, bytes.NewReader(reqBody))
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("Authorization", "Bearer "+p.opts.APIKey)
+
+	httpResp, err := http.DefaultClient.Do(httpReq)
+	if err != nil {
+		return nil, nil, fmt.Errorf("API request failed: %w", err)
+	}
+	defer httpResp.Body.Close()
+
+	respBody, _ := io.ReadAll(httpResp.Body)
+	if httpResp.StatusCode != http.StatusOK {
+		return nil, nil, fmt.Errorf("API error (%s): %s", httpResp.Status, string(respBody))
+	}
+
+	var chatResp struct {
+		Choices []struct {
+			Message struct {
+				Content   string `json:"content"`
+				ToolCalls []struct {
+					ID       string `json:"id"`
+					Function struct {
+						Name      string `json:"name"`
+						Arguments string `json:"arguments"`
+					} `json:"function"`
+				} `json:"tool_calls"`
+			} `json:"message"`
+		} `json:"choices"`
+	}
+
+	if err := json.Unmarshal(respBody, &chatResp); err != nil {
+		return nil, nil, fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	if len(chatResp.Choices) == 0 {
+		return nil, nil, fmt.Errorf("no response from API")
+	}
+
+	choice := chatResp.Choices[0]
+	response := &ai.Response{
+		Reply: choice.Message.Content,
+	}
+
+	for _, tc := range choice.Message.ToolCalls {
+		var input map[string]any
+		if err := json.Unmarshal([]byte(tc.Function.Arguments), &input); err != nil {
+			input = map[string]any{}
+		}
+		response.ToolCalls = append(response.ToolCalls, ai.ToolCall{
+			ID:    tc.ID,
+			Name:  tc.Function.Name,
+			Input: input,
+		})
+	}
+
+	rawMessage := map[string]any{
+		"content":    choice.Message.Content,
+		"tool_calls": choice.Message.ToolCalls,
+	}
+
+	return response, rawMessage, nil
+}
+
+const defaultImageModel = "openai/gpt-image-2/text-to-image"
+
+// GenerateImage creates an image using Atlas Cloud's async image API.
+// It submits the job and polls until completion or context cancellation.
+func (p *Provider) GenerateImage(ctx context.Context, req *ai.ImageRequest, opts ...ai.GenerateOption) (*ai.ImageResponse, error) {
+	model := req.Model
+	if model == "" {
+		model = defaultImageModel
+	}
+	quality := req.Quality
+	if quality == "" {
+		quality = "medium"
+	}
+	outputFmt := req.OutputFormat
+	if outputFmt == "" {
+		outputFmt = "png"
+	}
+	size := req.Size
+	if size == "" {
+		size = "1024x1024"
+	}
+
+	apiReq := map[string]any{
+		"model":                model,
+		"prompt":               req.Prompt,
+		"quality":              quality,
+		"output_format":        outputFmt,
+		"size":                 size,
+		"enable_sync_mode":     false,
+		"enable_base64_output": false,
+		"moderation":           "low",
+	}
+
+	reqBody, err := json.Marshal(apiReq)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	apiURL := strings.TrimRight(p.opts.BaseURL, "/") + "/api/v1/model/generateImage"
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, bytes.NewReader(reqBody))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("Authorization", "Bearer "+p.opts.APIKey)
+
+	httpResp, err := http.DefaultClient.Do(httpReq)
+	if err != nil {
+		return nil, fmt.Errorf("API request failed: %w", err)
+	}
+	defer httpResp.Body.Close()
+
+	respBody, _ := io.ReadAll(httpResp.Body)
+	if httpResp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("API error (%s): %s", httpResp.Status, string(respBody))
+	}
+
+	var submitResp struct {
+		Code int    `json:"code"`
+		Msg  string `json:"message"`
+		Data struct {
+			ID     string `json:"id"`
+			Status string `json:"status"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(respBody, &submitResp); err != nil {
+		return nil, fmt.Errorf("failed to parse submit response: %w", err)
+	}
+	if submitResp.Code != 200 {
+		return nil, fmt.Errorf("API error: %s", submitResp.Msg)
+	}
+
+	predictionID := submitResp.Data.ID
+	pollURL := strings.TrimRight(p.opts.BaseURL, "/") + "/api/v1/model/prediction/" + predictionID
+
+	ticker := time.NewTicker(2 * time.Second)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case <-ticker.C:
+			result, err := p.pollPrediction(ctx, pollURL)
+			if err != nil {
+				return nil, err
+			}
+			if result != nil {
+				return result, nil
+			}
+		}
+	}
+}
+
+func (p *Provider) pollPrediction(ctx context.Context, url string) (*ai.ImageResponse, error) {
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, err
+	}
+	httpReq.Header.Set("Authorization", "Bearer "+p.opts.APIKey)
+
+	httpResp, err := http.DefaultClient.Do(httpReq)
+	if err != nil {
+		return nil, fmt.Errorf("poll request failed: %w", err)
+	}
+	defer httpResp.Body.Close()
+
+	body, _ := io.ReadAll(httpResp.Body)
+
+	var pollResp struct {
+		Data struct {
+			Status  string   `json:"status"`
+			Outputs []string `json:"outputs"`
+			Error   string   `json:"error"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(body, &pollResp); err != nil {
+		return nil, fmt.Errorf("failed to parse poll response: %w", err)
+	}
+
+	switch pollResp.Data.Status {
+	case "completed":
+		resp := &ai.ImageResponse{}
+		for _, output := range pollResp.Data.Outputs {
+			resp.Images = append(resp.Images, ai.Image{URL: output})
+		}
+		return resp, nil
+	case "failed":
+		return nil, fmt.Errorf("image generation failed: %s", pollResp.Data.Error)
+	default:
+		return nil, nil
+	}
+}
+
+const defaultVideoModel = "google/gemini-omni-flash/image-to-video-developer"
+
+// GenerateVideo creates a video using Atlas Cloud's async video API.
+// Supports text-to-video and image-to-video depending on whether
+// Images are provided in the request.
+func (p *Provider) GenerateVideo(ctx context.Context, req *ai.VideoRequest, opts ...ai.GenerateOption) (*ai.VideoResponse, error) {
+	model := req.Model
+	if model == "" {
+		model = defaultVideoModel
+	}
+	duration := req.Duration
+	if duration <= 0 {
+		duration = 6
+	}
+	aspect := req.AspectRatio
+	if aspect == "" {
+		aspect = "16:9"
+	}
+	resolution := req.Resolution
+	if resolution == "" {
+		resolution = "720p"
+	}
+
+	apiReq := map[string]any{
+		"model":        model,
+		"prompt":       req.Prompt,
+		"duration":     duration,
+		"aspect_ratio": aspect,
+		"resolution":   resolution,
+		"seed":         -1,
+	}
+	if len(req.Images) > 0 {
+		apiReq["images"] = req.Images
+	}
+
+	reqBody, err := json.Marshal(apiReq)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	apiURL := strings.TrimRight(p.opts.BaseURL, "/") + "/api/v1/model/generateVideo"
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, bytes.NewReader(reqBody))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("Authorization", "Bearer "+p.opts.APIKey)
+
+	httpResp, err := http.DefaultClient.Do(httpReq)
+	if err != nil {
+		return nil, fmt.Errorf("API request failed: %w", err)
+	}
+	defer httpResp.Body.Close()
+
+	respBody, _ := io.ReadAll(httpResp.Body)
+	if httpResp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("API error (%s): %s", httpResp.Status, string(respBody))
+	}
+
+	var submitResp struct {
+		Code int    `json:"code"`
+		Msg  string `json:"message"`
+		Data struct {
+			ID     string `json:"id"`
+			Status string `json:"status"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(respBody, &submitResp); err != nil {
+		return nil, fmt.Errorf("failed to parse submit response: %w", err)
+	}
+	if submitResp.Code != 200 {
+		return nil, fmt.Errorf("API error: %s", submitResp.Msg)
+	}
+
+	pollURL := strings.TrimRight(p.opts.BaseURL, "/") + "/api/v1/model/prediction/" + submitResp.Data.ID
+
+	ticker := time.NewTicker(5 * time.Second)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case <-ticker.C:
+			result, err := p.pollVideo(ctx, pollURL)
+			if err != nil {
+				return nil, err
+			}
+			if result != nil {
+				return result, nil
+			}
+		}
+	}
+}
+
+func (p *Provider) pollVideo(ctx context.Context, url string) (*ai.VideoResponse, error) {
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, err
+	}
+	httpReq.Header.Set("Authorization", "Bearer "+p.opts.APIKey)
+
+	httpResp, err := http.DefaultClient.Do(httpReq)
+	if err != nil {
+		return nil, fmt.Errorf("poll request failed: %w", err)
+	}
+	defer httpResp.Body.Close()
+
+	body, _ := io.ReadAll(httpResp.Body)
+
+	var pollResp struct {
+		Data struct {
+			Status  string   `json:"status"`
+			Outputs []string `json:"outputs"`
+			Error   string   `json:"error"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(body, &pollResp); err != nil {
+		return nil, fmt.Errorf("failed to parse poll response: %w", err)
+	}
+
+	switch pollResp.Data.Status {
+	case "completed", "succeeded":
+		if len(pollResp.Data.Outputs) == 0 {
+			return nil, fmt.Errorf("video completed but no outputs returned")
+		}
+		return &ai.VideoResponse{URL: pollResp.Data.Outputs[0]}, nil
+	case "failed":
+		return nil, fmt.Errorf("video generation failed: %s", pollResp.Data.Error)
+	default:
+		return nil, nil
+	}
+}

ai/atlascloud/atlascloud_test.go

@@ -0,0 +1,148 @@
+package atlascloud
+
+import (
+	"context"
+	"testing"
+
+	"go-micro.dev/v6/ai"
+)
+
+func TestProvider_String(t *testing.T) {
+	p := NewProvider()
+	if p.String() != "atlascloud" {
+		t.Errorf("Expected provider name 'atlascloud', got '%s'", p.String())
+	}
+}
+
+func TestProvider_Init(t *testing.T) {
+	p := NewProvider()
+
+	err := p.Init(
+		ai.WithModel("test-model"),
+		ai.WithAPIKey("test-key"),
+		ai.WithBaseURL("https://test.com"),
+	)
+
+	if err != nil {
+		t.Fatalf("Init failed: %v", err)
+	}
+
+	opts := p.Options()
+	if opts.Model != "test-model" {
+		t.Errorf("Expected model 'test-model', got '%s'", opts.Model)
+	}
+	if opts.APIKey != "test-key" {
+		t.Errorf("Expected API key 'test-key', got '%s'", opts.APIKey)
+	}
+	if opts.BaseURL != "https://test.com" {
+		t.Errorf("Expected base URL 'https://test.com', got '%s'", opts.BaseURL)
+	}
+}
+
+func TestProvider_Options(t *testing.T) {
+	p := NewProvider(
+		ai.WithModel("custom-model"),
+		ai.WithAPIKey("my-key"),
+	)
+
+	opts := p.Options()
+	if opts.Model != "custom-model" {
+		t.Errorf("Expected model 'custom-model', got '%s'", opts.Model)
+	}
+	if opts.APIKey != "my-key" {
+		t.Errorf("Expected API key 'my-key', got '%s'", opts.APIKey)
+	}
+}
+
+func TestProvider_Defaults(t *testing.T) {
+	p := NewProvider()
+
+	opts := p.Options()
+	if opts.Model != "deepseek-ai/DeepSeek-V3-0324" {
+		t.Errorf("Expected default model 'deepseek-ai/DeepSeek-V3-0324', got '%s'", opts.Model)
+	}
+	if opts.BaseURL != "https://api.atlascloud.ai" {
+		t.Errorf("Expected default base URL 'https://api.atlascloud.ai', got '%s'", opts.BaseURL)
+	}
+}
+
+func TestProvider_Generate_NoAPIKey(t *testing.T) {
+	p := NewProvider()
+
+	req := &ai.Request{
+		Prompt:       "Hello",
+		SystemPrompt: "You are helpful",
+	}
+
+	_, err := p.Generate(context.Background(), req)
+	if err == nil {
+		t.Error("Expected error when API key is missing, got nil")
+	}
+}
+
+func TestProvider_Stream_NotImplemented(t *testing.T) {
+	p := NewProvider()
+
+	req := &ai.Request{
+		Prompt: "Hello",
+	}
+
+	_, err := p.Stream(context.Background(), req)
+	if err == nil {
+		t.Error("Expected error for unimplemented streaming, got nil")
+	}
+}
+
+func TestProvider_Registration(t *testing.T) {
+	m := ai.New("atlascloud", ai.WithAPIKey("test"))
+	if m == nil {
+		t.Fatal("ai.New('atlascloud') returned nil — provider not registered")
+	}
+	if m.String() != "atlascloud" {
+		t.Errorf("Expected 'atlascloud', got '%s'", m.String())
+	}
+}
+
+func TestProvider_ImageRegistration(t *testing.T) {
+	ig := ai.NewImage("atlascloud", ai.WithAPIKey("test"))
+	if ig == nil {
+		t.Fatal("ai.NewImage('atlascloud') returned nil — image provider not registered")
+	}
+	if ig.String() != "atlascloud" {
+		t.Errorf("Expected 'atlascloud', got '%s'", ig.String())
+	}
+}
+
+func TestProvider_GenerateImage_NoAPIKey(t *testing.T) {
+	p := NewProvider()
+	_, err := p.GenerateImage(context.Background(), &ai.ImageRequest{Prompt: "a cat"})
+	if err == nil {
+		t.Error("Expected error when API key is missing, got nil")
+	}
+}
+
+func TestProvider_ImplementsImageModel(t *testing.T) {
+	var _ ai.ImageModel = (*Provider)(nil)
+}
+
+func TestProvider_VideoRegistration(t *testing.T) {
+	vg := ai.NewVideo("atlascloud", ai.WithAPIKey("test"))
+	if vg == nil {
+		t.Fatal("ai.NewVideo('atlascloud') returned nil — video provider not registered")
+	}
+	if vg.String() != "atlascloud" {
+		t.Errorf("Expected 'atlascloud', got '%s'", vg.String())
+	}
+}
+
+func TestProvider_GenerateVideo_NoAPIKey(t *testing.T) {
+	p := NewProvider()
+	_, err := p.GenerateVideo(context.Background(), &ai.VideoRequest{Prompt: "a cat"})
+	if err == nil {
+		t.Error("Expected error when API key is missing, got nil")
+	}
+}
+
+func TestProvider_ImplementsVideoModel(t *testing.T) {
+	var _ ai.VideoModel = (*Provider)(nil)
+}

ai/flow/compat.go

@@ -0,0 +1,22 @@
+// Package flow is maintained for backward compatibility.
+// The canonical import is go-micro.dev/v6/flow.
+package flow
+
+import "go-micro.dev/v6/flow"
+
+// Re-export types for backward compatibility.
+type Flow = flow.Flow
+type Options = flow.Options
+type Option = flow.Option
+type Result = flow.Result
+
+var New = flow.New
+var Trigger = flow.Trigger
+var Prompt = flow.Prompt
+var SystemPrompt = flow.SystemPrompt
+var Provider = flow.Provider
+var APIKey = flow.APIKey
+var Model = flow.Model
+var BaseURL = flow.BaseURL
+var HistoryLimit = flow.HistoryLimit
+var OnResult = flow.OnResult

ai/gemini/gemini.go

@@ -0,0 +1,226 @@
+// Package gemini implements the Google Gemini model provider.
+//
+// Usage:
+//
+//	import _ "go-micro.dev/v6/ai/gemini"
+//
+//	m := ai.New("gemini",
+//	    ai.WithAPIKey("your-api-key"),
+//	)
+package gemini
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"go-micro.dev/v6/ai"
+)
+
+func init() {
+	ai.Register("gemini", func(opts ...ai.Option) ai.Model {
+		return NewProvider(opts...)
+	})
+}
+
+// Provider implements the ai.Model interface for Google Gemini.
+type Provider struct {
+	opts ai.Options
+}
+
+// NewProvider creates a new Gemini provider.
+func NewProvider(opts ...ai.Option) *Provider {
+	options := ai.NewOptions(opts...)
+
+	if options.Model == "" {
+		options.Model = "gemini-2.5-flash"
+	}
+	if options.BaseURL == "" {
+		options.BaseURL = "https://generativelanguage.googleapis.com"
+	}
+
+	return &Provider{opts: options}
+}
+
+func (p *Provider) Init(opts ...ai.Option) error {
+	for _, o := range opts {
+		o(&p.opts)
+	}
+	return nil
+}
+
+func (p *Provider) Options() ai.Options { return p.opts }
+func (p *Provider) String() string      { return "gemini" }
+
+func (p *Provider) Generate(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (*ai.Response, error) {
+	var tools []map[string]any
+	for _, t := range req.Tools {
+		tools = append(tools, map[string]any{
+			"name":        t.Name,
+			"description": t.Description,
+			"parameters": map[string]any{
+				"type":       "object",
+				"properties": t.Properties,
+			},
+		})
+	}
+
+	contents := []map[string]any{
+		{"role": "user", "parts": []map[string]any{{"text": req.Prompt}}},
+	}
+
+	apiReq := map[string]any{
+		"contents": contents,
+	}
+
+	if req.SystemPrompt != "" {
+		apiReq["system_instruction"] = map[string]any{
+			"parts": []map[string]any{{"text": req.SystemPrompt}},
+		}
+	}
+
+	if len(tools) > 0 {
+		apiReq["tools"] = []map[string]any{
+			{"functionDeclarations": tools},
+		}
+	}
+
+	resp, rawParts, err := p.callAPI(ctx, apiReq)
+	if err != nil {
+		return nil, err
+	}
+
+	if len(resp.ToolCalls) == 0 {
+		return resp, nil
+	}
+
+	if p.opts.ToolHandler != nil {
+		var resultParts []map[string]any
+		for _, tc := range resp.ToolCalls {
+			result := p.opts.ToolHandler(ctx, tc).Value
+			resultParts = append(resultParts, map[string]any{
+				"functionResponse": map[string]any{
+					"name":     tc.Name,
+					"id":       tc.ID,
+					"response": result,
+				},
+			})
+		}
+
+		followUpContents := append(contents,
+			map[string]any{"role": "model", "parts": rawParts},
+			map[string]any{"role": "user", "parts": resultParts},
+		)
+
+		followUpReq := map[string]any{
+			"contents": followUpContents,
+		}
+		if req.SystemPrompt != "" {
+			followUpReq["system_instruction"] = map[string]any{
+				"parts": []map[string]any{{"text": req.SystemPrompt}},
+			}
+		}
+
+		followUpResp, _, err := p.callAPI(ctx, followUpReq)
+		if err == nil && followUpResp.Reply != "" {
+			resp.Answer = followUpResp.Reply
+		}
+	}
+
+	return resp, nil
+}
+
+func (p *Provider) Stream(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (ai.Stream, error) {
+	return nil, fmt.Errorf("streaming not yet implemented for gemini provider")
+}
+
+func (p *Provider) callAPI(ctx context.Context, req map[string]any) (*ai.Response, []map[string]any, error) {
+	reqBody, err := json.Marshal(req)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	apiURL := strings.TrimRight(p.opts.BaseURL, "/") +
+		"/v1beta/models/" + p.opts.Model + ":generateContent"
+
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, bytes.NewReader(reqBody))
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("x-goog-api-key", p.opts.APIKey)
+
+	httpResp, err := http.DefaultClient.Do(httpReq)
+	if err != nil {
+		return nil, nil, fmt.Errorf("API request failed: %w", err)
+	}
+	defer httpResp.Body.Close()
+
+	respBody, _ := io.ReadAll(httpResp.Body)
+	if httpResp.StatusCode != http.StatusOK {
+		return nil, nil, fmt.Errorf("API error (%s): %s", httpResp.Status, string(respBody))
+	}
+
+	var geminiResp struct {
+		Candidates []struct {
+			Content struct {
+				Parts []struct {
+					Text         string          `json:"text"`
+					FunctionCall *functionCallPB `json:"functionCall"`
+				} `json:"parts"`
+			} `json:"content"`
+		} `json:"candidates"`
+	}
+
+	if err := json.Unmarshal(respBody, &geminiResp); err != nil {
+		return nil, nil, fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	if len(geminiResp.Candidates) == 0 {
+		return nil, nil, fmt.Errorf("no response from API")
+	}
+
+	parts := geminiResp.Candidates[0].Content.Parts
+	response := &ai.Response{}
+
+	var replyParts []string
+	var rawParts []map[string]any
+
+	for _, part := range parts {
+		if part.Text != "" {
+			replyParts = append(replyParts, part.Text)
+			rawParts = append(rawParts, map[string]any{"text": part.Text})
+		}
+		if part.FunctionCall != nil {
+			response.ToolCalls = append(response.ToolCalls, ai.ToolCall{
+				ID:    part.FunctionCall.ID,
+				Name:  part.FunctionCall.Name,
+				Input: part.FunctionCall.Args,
+			})
+			rawParts = append(rawParts, map[string]any{
+				"functionCall": map[string]any{
+					"id":   part.FunctionCall.ID,
+					"name": part.FunctionCall.Name,
+					"args": part.FunctionCall.Args,
+				},
+			})
+		}
+	}
+
+	if len(replyParts) > 0 {
+		response.Reply = strings.Join(replyParts, "\n")
+	}
+
+	return response, rawParts, nil
+}
+
+type functionCallPB struct {
+	ID   string         `json:"id"`
+	Name string         `json:"name"`
+	Args map[string]any `json:"args"`
+}

ai/gemini/gemini_test.go

@@ -0,0 +1,104 @@
+package gemini
+
+import (
+	"context"
+	"testing"
+
+	"go-micro.dev/v6/ai"
+)
+
+func TestProvider_String(t *testing.T) {
+	p := NewProvider()
+	if p.String() != "gemini" {
+		t.Errorf("Expected provider name 'gemini', got '%s'", p.String())
+	}
+}
+
+func TestProvider_Init(t *testing.T) {
+	p := NewProvider()
+
+	err := p.Init(
+		ai.WithModel("gemini-2.0-flash"),
+		ai.WithAPIKey("test-key"),
+		ai.WithBaseURL("https://test.com"),
+	)
+
+	if err != nil {
+		t.Fatalf("Init failed: %v", err)
+	}
+
+	opts := p.Options()
+	if opts.Model != "gemini-2.0-flash" {
+		t.Errorf("Expected model 'gemini-2.0-flash', got '%s'", opts.Model)
+	}
+	if opts.APIKey != "test-key" {
+		t.Errorf("Expected API key 'test-key', got '%s'", opts.APIKey)
+	}
+	if opts.BaseURL != "https://test.com" {
+		t.Errorf("Expected base URL 'https://test.com', got '%s'", opts.BaseURL)
+	}
+}
+
+func TestProvider_Options(t *testing.T) {
+	p := NewProvider(
+		ai.WithModel("custom-model"),
+		ai.WithAPIKey("my-key"),
+	)
+
+	opts := p.Options()
+	if opts.Model != "custom-model" {
+		t.Errorf("Expected model 'custom-model', got '%s'", opts.Model)
+	}
+	if opts.APIKey != "my-key" {
+		t.Errorf("Expected API key 'my-key', got '%s'", opts.APIKey)
+	}
+}
+
+func TestProvider_Defaults(t *testing.T) {
+	p := NewProvider()
+
+	opts := p.Options()
+	if opts.Model != "gemini-2.5-flash" {
+		t.Errorf("Expected default model 'gemini-2.5-flash', got '%s'", opts.Model)
+	}
+	if opts.BaseURL != "https://generativelanguage.googleapis.com" {
+		t.Errorf("Expected default base URL 'https://generativelanguage.googleapis.com', got '%s'", opts.BaseURL)
+	}
+}
+
+func TestProvider_Generate_NoAPIKey(t *testing.T) {
+	p := NewProvider()
+
+	req := &ai.Request{
+		Prompt:       "Hello",
+		SystemPrompt: "You are helpful",
+	}
+
+	_, err := p.Generate(context.Background(), req)
+	if err == nil {
+		t.Error("Expected error when API key is missing, got nil")
+	}
+}
+
+func TestProvider_Stream_NotImplemented(t *testing.T) {
+	p := NewProvider()
+
+	req := &ai.Request{
+		Prompt: "Hello",
+	}
+
+	_, err := p.Stream(context.Background(), req)
+	if err == nil {
+		t.Error("Expected error for unimplemented streaming, got nil")
+	}
+}
+
+func TestProvider_Registration(t *testing.T) {
+	m := ai.New("gemini", ai.WithAPIKey("test"))
+	if m == nil {
+		t.Fatal("ai.New('gemini') returned nil — provider not registered")
+	}
+	if m.String() != "gemini" {
+		t.Errorf("Expected 'gemini', got '%s'", m.String())
+	}
+}

ai/groq/groq.go

@@ -0,0 +1,194 @@
+// Package groq implements the Groq model provider.
+//
+// Groq provides ultra-fast inference for open-weight models via an
+// OpenAI-compatible chat completions endpoint.
+//
+// Usage:
+//
+//	import _ "go-micro.dev/v6/ai/groq"
+//
+//	m := ai.New("groq",
+//	    ai.WithAPIKey("your-api-key"),
+//	)
+package groq
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"go-micro.dev/v6/ai"
+)
+
+func init() {
+	ai.Register("groq", func(opts ...ai.Option) ai.Model {
+		return NewProvider(opts...)
+	})
+}
+
+type Provider struct {
+	opts ai.Options
+}
+
+func NewProvider(opts ...ai.Option) *Provider {
+	options := ai.NewOptions(opts...)
+	if options.Model == "" {
+		options.Model = "llama-3.3-70b-versatile"
+	}
+	if options.BaseURL == "" {
+		options.BaseURL = "https://api.groq.com/openai"
+	}
+	return &Provider{opts: options}
+}
+
+func (p *Provider) Init(opts ...ai.Option) error {
+	for _, o := range opts {
+		o(&p.opts)
+	}
+	return nil
+}
+
+func (p *Provider) Options() ai.Options { return p.opts }
+func (p *Provider) String() string      { return "groq" }
+
+func (p *Provider) Generate(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (*ai.Response, error) {
+	var tools []map[string]any
+	for _, t := range req.Tools {
+		tools = append(tools, map[string]any{
+			"type": "function",
+			"function": map[string]any{
+				"name":        t.Name,
+				"description": t.Description,
+				"parameters": map[string]any{
+					"type":       "object",
+					"properties": t.Properties,
+				},
+			},
+		})
+	}
+
+	messages := []map[string]any{
+		{"role": "system", "content": req.SystemPrompt},
+		{"role": "user", "content": req.Prompt},
+	}
+
+	apiReq := map[string]any{
+		"model":    p.opts.Model,
+		"messages": messages,
+	}
+	if len(tools) > 0 {
+		apiReq["tools"] = tools
+	}
+
+	resp, rawMessage, err := p.callAPI(ctx, apiReq)
+	if err != nil {
+		return nil, err
+	}
+	if len(resp.ToolCalls) == 0 {
+		return resp, nil
+	}
+
+	if p.opts.ToolHandler != nil {
+		followUpMessages := append(messages, map[string]any{
+			"role":       "assistant",
+			"content":    rawMessage["content"],
+			"tool_calls": rawMessage["tool_calls"],
+		})
+		for _, tc := range resp.ToolCalls {
+			content := p.opts.ToolHandler(ctx, tc).Content
+			followUpMessages = append(followUpMessages, map[string]any{
+				"role":         "tool",
+				"tool_call_id": tc.ID,
+				"content":      content,
+			})
+		}
+		followUpResp, _, err := p.callAPI(ctx, map[string]any{
+			"model":    p.opts.Model,
+			"messages": followUpMessages,
+		})
+		if err == nil && followUpResp.Reply != "" {
+			resp.Answer = followUpResp.Reply
+		}
+	}
+
+	return resp, nil
+}
+
+func (p *Provider) Stream(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (ai.Stream, error) {
+	return nil, fmt.Errorf("streaming not yet implemented for groq provider")
+}
+
+func (p *Provider) callAPI(ctx context.Context, req map[string]any) (*ai.Response, map[string]any, error) {
+	reqBody, err := json.Marshal(req)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	apiURL := strings.TrimRight(p.opts.BaseURL, "/") + "/v1/chat/completions"
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, bytes.NewReader(reqBody))
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("Authorization", "Bearer "+p.opts.APIKey)
+
+	httpResp, err := http.DefaultClient.Do(httpReq)
+	if err != nil {
+		return nil, nil, fmt.Errorf("API request failed: %w", err)
+	}
+	defer httpResp.Body.Close()
+
+	respBody, _ := io.ReadAll(httpResp.Body)
+	if httpResp.StatusCode != http.StatusOK {
+		return nil, nil, fmt.Errorf("API error (%s): %s", httpResp.Status, string(respBody))
+	}
+
+	var chatResp struct {
+		Choices []struct {
+			Message struct {
+				Content   string `json:"content"`
+				ToolCalls []struct {
+					ID       string `json:"id"`
+					Function struct {
+						Name      string `json:"name"`
+						Arguments string `json:"arguments"`
+					} `json:"function"`
+				} `json:"tool_calls"`
+			} `json:"message"`
+		} `json:"choices"`
+	}
+
+	if err := json.Unmarshal(respBody, &chatResp); err != nil {
+		return nil, nil, fmt.Errorf("failed to parse response: %w", err)
+	}
+	if len(chatResp.Choices) == 0 {
+		return nil, nil, fmt.Errorf("no response from API")
+	}
+
+	choice := chatResp.Choices[0]
+	response := &ai.Response{Reply: choice.Message.Content}
+
+	for _, tc := range choice.Message.ToolCalls {
+		var input map[string]any
+		if err := json.Unmarshal([]byte(tc.Function.Arguments), &input); err != nil {
+			input = map[string]any{}
+		}
+		response.ToolCalls = append(response.ToolCalls, ai.ToolCall{
+			ID:    tc.ID,
+			Name:  tc.Function.Name,
+			Input: input,
+		})
+	}
+
+	rawMessage := map[string]any{
+		"content":    choice.Message.Content,
+		"tool_calls": choice.Message.ToolCalls,
+	}
+
+	return response, rawMessage, nil
+}

ai/groq/groq_test.go

@@ -0,0 +1,56 @@
+package groq
+
+import (
+	"context"
+	"testing"
+
+	"go-micro.dev/v6/ai"
+)
+
+func TestProvider_String(t *testing.T) {
+	if NewProvider().String() != "groq" {
+		t.Errorf("got %q", NewProvider().String())
+	}
+}
+
+func TestProvider_Defaults(t *testing.T) {
+	opts := NewProvider().Options()
+	if opts.Model != "llama-3.3-70b-versatile" {
+		t.Errorf("default model = %q", opts.Model)
+	}
+	if opts.BaseURL != "https://api.groq.com/openai" {
+		t.Errorf("default base URL = %q", opts.BaseURL)
+	}
+}
+
+func TestProvider_Init(t *testing.T) {
+	p := NewProvider()
+	if err := p.Init(ai.WithModel("m"), ai.WithAPIKey("k")); err != nil {
+		t.Fatal(err)
+	}
+	if p.Options().Model != "m" || p.Options().APIKey != "k" {
+		t.Error("Init did not apply options")
+	}
+}
+
+func TestProvider_Generate_NoAPIKey(t *testing.T) {
+	if _, err := NewProvider().Generate(context.Background(), &ai.Request{Prompt: "hi"}); err == nil {
+		t.Error("expected error without API key")
+	}
+}
+
+func TestProvider_Stream_NotImplemented(t *testing.T) {
+	if _, err := NewProvider().Stream(context.Background(), &ai.Request{Prompt: "hi"}); err == nil {
+		t.Error("expected error")
+	}
+}
+
+func TestProvider_Registration(t *testing.T) {
+	m := ai.New("groq", ai.WithAPIKey("test"))
+	if m == nil {
+		t.Fatal("provider not registered")
+	}
+	if m.String() != "groq" {
+		t.Errorf("got %q", m.String())
+	}
+}

ai/history.go

@@ -0,0 +1,45 @@
+package ai
+
+// History is a convenience for accumulating conversation messages
+// with automatic truncation. Use it to build Request.Messages for
+// multi-turn conversations.
+//
+//	hist := ai.NewHistory(50)
+//	hist.Add("user", "hello")
+//	resp, _ := m.Generate(ctx, &ai.Request{Messages: hist.Messages(), Prompt: "next"})
+//	hist.Add("assistant", resp.Reply)
+type History struct {
+	messages []Message
+	limit    int
+}
+
+// NewHistory creates an empty History. limit controls the maximum
+// number of messages retained (0 = unlimited).
+func NewHistory(limit int) *History {
+	return &History{limit: limit}
+}
+
+// Add appends a message and truncates if over limit.
+func (h *History) Add(role string, content any) {
+	h.messages = append(h.messages, Message{Role: role, Content: content})
+	if h.limit > 0 && len(h.messages) > h.limit {
+		h.messages = h.messages[len(h.messages)-h.limit:]
+	}
+}
+
+// Messages returns a copy of the accumulated messages.
+func (h *History) Messages() []Message {
+	out := make([]Message, len(h.messages))
+	copy(out, h.messages)
+	return out
+}
+
+// Len returns the number of messages.
+func (h *History) Len() int {
+	return len(h.messages)
+}
+
+// Reset clears all messages.
+func (h *History) Reset() {
+	h.messages = nil
+}

ai/history_test.go

@@ -0,0 +1,62 @@
+package ai
+
+import "testing"
+
+func TestHistory_Add(t *testing.T) {
+	h := NewHistory(0)
+	h.Add("user", "hello")
+	h.Add("assistant", "hi")
+
+	if h.Len() != 2 {
+		t.Errorf("len = %d, want 2", h.Len())
+	}
+	msgs := h.Messages()
+	if msgs[0].Role != "user" || msgs[0].Content != "hello" {
+		t.Errorf("first = %+v", msgs[0])
+	}
+	if msgs[1].Role != "assistant" || msgs[1].Content != "hi" {
+		t.Errorf("second = %+v", msgs[1])
+	}
+}
+
+func TestHistory_Truncation(t *testing.T) {
+	h := NewHistory(3)
+	for _, m := range []string{"a", "b", "c", "d", "e"} {
+		h.Add("user", m)
+	}
+	if h.Len() != 3 {
+		t.Errorf("len = %d, want 3", h.Len())
+	}
+	if h.Messages()[0].Content != "c" {
+		t.Errorf("first retained = %+v", h.Messages()[0])
+	}
+}
+
+func TestHistory_Reset(t *testing.T) {
+	h := NewHistory(0)
+	h.Add("user", "hello")
+	h.Reset()
+	if h.Len() != 0 {
+		t.Errorf("len after reset = %d", h.Len())
+	}
+}
+
+func TestHistory_SnapshotIsCopy(t *testing.T) {
+	h := NewHistory(0)
+	h.Add("user", "hello")
+	msgs := h.Messages()
+	msgs[0].Content = "mutated"
+	if h.Messages()[0].Content == "mutated" {
+		t.Error("snapshot returned reference, not copy")
+	}
+}
+
+func TestHistory_Unlimited(t *testing.T) {
+	h := NewHistory(0)
+	for i := 0; i < 100; i++ {
+		h.Add("user", "msg")
+	}
+	if h.Len() != 100 {
+		t.Errorf("len = %d, want 100", h.Len())
+	}
+}

ai/image.go

@@ -0,0 +1,65 @@
+package ai
+
+import "context"
+
+// ImageModel provides an interface for image generation providers.
+// Providers that support image generation implement this alongside
+// or instead of Model. Use NewImage to construct, or type-assert
+// a provider that implements both:
+//
+//	p := atlascloud.NewProvider(ai.WithAPIKey(key))
+//	if ig, ok := p.(ai.ImageModel); ok {
+//	    resp, _ := ig.GenerateImage(ctx, req)
+//	}
+type ImageModel interface {
+	GenerateImage(ctx context.Context, req *ImageRequest, opts ...GenerateOption) (*ImageResponse, error)
+	String() string
+}
+
+// ImageRequest describes what image to generate.
+type ImageRequest struct {
+	// Prompt is the text description of the image to generate.
+	Prompt string
+	// Model overrides the provider's default image model.
+	Model string
+	// Size of the generated image (e.g. "1024x1024"). Provider-specific.
+	Size string
+	// N is the number of images to generate. Defaults to 1.
+	N int
+	// Quality controls generation quality. Provider-specific (e.g. "low", "medium", "high").
+	Quality string
+	// OutputFormat sets the image format (e.g. "png", "jpeg"). Provider-specific.
+	OutputFormat string
+}
+
+// ImageResponse holds the generated images.
+type ImageResponse struct {
+	Images []Image
+}
+
+// Image is a single generated image, returned as a URL, base64 data, or both
+// depending on the provider and request options.
+type Image struct {
+	// URL is a remote URL where the image can be fetched.
+	URL string
+	// Base64 is the base64-encoded image data.
+	Base64 string
+}
+
+// NewImageFunc creates a new ImageModel instance.
+type NewImageFunc func(...Option) ImageModel
+
+var imageProviders = make(map[string]NewImageFunc)
+
+// RegisterImage registers an image generation provider.
+func RegisterImage(name string, fn NewImageFunc) {
+	imageProviders[name] = fn
+}
+
+// NewImage creates a new ImageModel instance based on the provider name.
+func NewImage(provider string, opts ...Option) ImageModel {
+	if fn, ok := imageProviders[provider]; ok {
+		return fn(opts...)
+	}
+	return nil
+}

ai/mistral/mistral.go

@@ -0,0 +1,194 @@
+// Package mistral implements the Mistral AI model provider.
+//
+// Mistral AI is a European AI company offering high-performance models
+// via an OpenAI-compatible chat completions endpoint.
+//
+// Usage:
+//
+//	import _ "go-micro.dev/v6/ai/mistral"
+//
+//	m := ai.New("mistral",
+//	    ai.WithAPIKey("your-api-key"),
+//	)
+package mistral
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"go-micro.dev/v6/ai"
+)
+
+func init() {
+	ai.Register("mistral", func(opts ...ai.Option) ai.Model {
+		return NewProvider(opts...)
+	})
+}
+
+type Provider struct {
+	opts ai.Options
+}
+
+func NewProvider(opts ...ai.Option) *Provider {
+	options := ai.NewOptions(opts...)
+	if options.Model == "" {
+		options.Model = "mistral-large-latest"
+	}
+	if options.BaseURL == "" {
+		options.BaseURL = "https://api.mistral.ai"
+	}
+	return &Provider{opts: options}
+}
+
+func (p *Provider) Init(opts ...ai.Option) error {
+	for _, o := range opts {
+		o(&p.opts)
+	}
+	return nil
+}
+
+func (p *Provider) Options() ai.Options { return p.opts }
+func (p *Provider) String() string      { return "mistral" }
+
+func (p *Provider) Generate(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (*ai.Response, error) {
+	var tools []map[string]any
+	for _, t := range req.Tools {
+		tools = append(tools, map[string]any{
+			"type": "function",
+			"function": map[string]any{
+				"name":        t.Name,
+				"description": t.Description,
+				"parameters": map[string]any{
+					"type":       "object",
+					"properties": t.Properties,
+				},
+			},
+		})
+	}
+
+	messages := []map[string]any{
+		{"role": "system", "content": req.SystemPrompt},
+		{"role": "user", "content": req.Prompt},
+	}
+
+	apiReq := map[string]any{
+		"model":    p.opts.Model,
+		"messages": messages,
+	}
+	if len(tools) > 0 {
+		apiReq["tools"] = tools
+	}
+
+	resp, rawMessage, err := p.callAPI(ctx, apiReq)
+	if err != nil {
+		return nil, err
+	}
+	if len(resp.ToolCalls) == 0 {
+		return resp, nil
+	}
+
+	if p.opts.ToolHandler != nil {
+		followUpMessages := append(messages, map[string]any{
+			"role":       "assistant",
+			"content":    rawMessage["content"],
+			"tool_calls": rawMessage["tool_calls"],
+		})
+		for _, tc := range resp.ToolCalls {
+			content := p.opts.ToolHandler(ctx, tc).Content
+			followUpMessages = append(followUpMessages, map[string]any{
+				"role":         "tool",
+				"tool_call_id": tc.ID,
+				"content":      content,
+			})
+		}
+		followUpResp, _, err := p.callAPI(ctx, map[string]any{
+			"model":    p.opts.Model,
+			"messages": followUpMessages,
+		})
+		if err == nil && followUpResp.Reply != "" {
+			resp.Answer = followUpResp.Reply
+		}
+	}
+
+	return resp, nil
+}
+
+func (p *Provider) Stream(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (ai.Stream, error) {
+	return nil, fmt.Errorf("streaming not yet implemented for mistral provider")
+}
+
+func (p *Provider) callAPI(ctx context.Context, req map[string]any) (*ai.Response, map[string]any, error) {
+	reqBody, err := json.Marshal(req)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	apiURL := strings.TrimRight(p.opts.BaseURL, "/") + "/v1/chat/completions"
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, bytes.NewReader(reqBody))
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("Authorization", "Bearer "+p.opts.APIKey)
+
+	httpResp, err := http.DefaultClient.Do(httpReq)
+	if err != nil {
+		return nil, nil, fmt.Errorf("API request failed: %w", err)
+	}
+	defer httpResp.Body.Close()
+
+	respBody, _ := io.ReadAll(httpResp.Body)
+	if httpResp.StatusCode != http.StatusOK {
+		return nil, nil, fmt.Errorf("API error (%s): %s", httpResp.Status, string(respBody))
+	}
+
+	var chatResp struct {
+		Choices []struct {
+			Message struct {
+				Content   string `json:"content"`
+				ToolCalls []struct {
+					ID       string `json:"id"`
+					Function struct {
+						Name      string `json:"name"`
+						Arguments string `json:"arguments"`
+					} `json:"function"`
+				} `json:"tool_calls"`
+			} `json:"message"`
+		} `json:"choices"`
+	}
+
+	if err := json.Unmarshal(respBody, &chatResp); err != nil {
+		return nil, nil, fmt.Errorf("failed to parse response: %w", err)
+	}
+	if len(chatResp.Choices) == 0 {
+		return nil, nil, fmt.Errorf("no response from API")
+	}
+
+	choice := chatResp.Choices[0]
+	response := &ai.Response{Reply: choice.Message.Content}
+
+	for _, tc := range choice.Message.ToolCalls {
+		var input map[string]any
+		if err := json.Unmarshal([]byte(tc.Function.Arguments), &input); err != nil {
+			input = map[string]any{}
+		}
+		response.ToolCalls = append(response.ToolCalls, ai.ToolCall{
+			ID:    tc.ID,
+			Name:  tc.Function.Name,
+			Input: input,
+		})
+	}
+
+	rawMessage := map[string]any{
+		"content":    choice.Message.Content,
+		"tool_calls": choice.Message.ToolCalls,
+	}
+
+	return response, rawMessage, nil
+}

ai/mistral/mistral_test.go

@@ -0,0 +1,56 @@
+package mistral
+
+import (
+	"context"
+	"testing"
+
+	"go-micro.dev/v6/ai"
+)
+
+func TestProvider_String(t *testing.T) {
+	if NewProvider().String() != "mistral" {
+		t.Errorf("got %q", NewProvider().String())
+	}
+}
+
+func TestProvider_Defaults(t *testing.T) {
+	opts := NewProvider().Options()
+	if opts.Model != "mistral-large-latest" {
+		t.Errorf("default model = %q", opts.Model)
+	}
+	if opts.BaseURL != "https://api.mistral.ai" {
+		t.Errorf("default base URL = %q", opts.BaseURL)
+	}
+}
+
+func TestProvider_Init(t *testing.T) {
+	p := NewProvider()
+	if err := p.Init(ai.WithModel("m"), ai.WithAPIKey("k")); err != nil {
+		t.Fatal(err)
+	}
+	if p.Options().Model != "m" || p.Options().APIKey != "k" {
+		t.Error("Init did not apply options")
+	}
+}
+
+func TestProvider_Generate_NoAPIKey(t *testing.T) {
+	if _, err := NewProvider().Generate(context.Background(), &ai.Request{Prompt: "hi"}); err == nil {
+		t.Error("expected error without API key")
+	}
+}
+
+func TestProvider_Stream_NotImplemented(t *testing.T) {
+	if _, err := NewProvider().Stream(context.Background(), &ai.Request{Prompt: "hi"}); err == nil {
+		t.Error("expected error")
+	}
+}
+
+func TestProvider_Registration(t *testing.T) {
+	m := ai.New("mistral", ai.WithAPIKey("test"))
+	if m == nil {
+		t.Fatal("provider not registered")
+	}
+	if m.String() != "mistral" {
+		t.Errorf("got %q", m.String())
+	}
+}

ai/model.go

@@ -0,0 +1,205 @@
+// Package ai provides abstraction for AI model providers
+package ai
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+)
+
+// Model provides an interface for interacting with AI model providers
+type Model interface {
+	// Init initializes the model with options
+	Init(...Option) error
+	// Options returns the model options
+	Options() Options
+	// Generate generates a response from the model
+	Generate(ctx context.Context, req *Request, opts ...GenerateOption) (*Response, error)
+	// Stream generates a streaming response (for future implementation)
+	Stream(ctx context.Context, req *Request, opts ...GenerateOption) (Stream, error)
+	// String returns the name of the provider
+	String() string
+}
+
+// Tool represents a tool/function that can be called by the model
+type Tool struct {
+	Name         string // LLM-safe name (e.g., "greeter_Greeter_Hello")
+	OriginalName string // Original name (e.g., "greeter.Greeter.Hello")
+	Description  string
+	Properties   map[string]any // JSON schema for tool parameters
+}
+
+// Request represents a request to generate content from a model
+type Request struct {
+	// Prompt is the user's message/prompt
+	Prompt string
+	// SystemPrompt is the system instruction for the model
+	SystemPrompt string
+	// Tools available for the model to use
+	Tools []Tool
+	// Messages for continuing a conversation (optional).
+	// Use ai.History to accumulate these across turns.
+	Messages []Message
+}
+
+// Message represents a conversation message
+type Message struct {
+	Role    string // "user", "assistant", "system", "tool"
+	Content any    // Can be string or structured content
+}
+
+// Response represents the response from a model
+type Response struct {
+	// Reply is the text response from the model
+	Reply string
+	// ToolCalls are tool calls requested by the model
+	ToolCalls []ToolCall
+	// Answer is the final answer after tool execution (if tools were used)
+	Answer string
+}
+
+// ToolCall represents a request to call a tool and its result
+type ToolCall struct {
+	ID     string         // Tool call ID (for correlation)
+	Name   string         // Tool name
+	Input  map[string]any // Tool input arguments
+	Result string         // Tool execution result (populated after execution)
+	Error  string         // Tool execution error (populated after execution)
+}
+
+// Scan decodes the call's Input into v (a pointer to a struct or map),
+// the same way a codec decodes an RPC request body. Use it when a tool
+// wants typed arguments instead of the raw map:
+//
+//	var args struct{ Query string `json:"query"` }
+//	if err := call.Scan(&args); err != nil { ... }
+func (c ToolCall) Scan(v any) error {
+	b, err := json.Marshal(c.Input)
+	if err != nil {
+		return err
+	}
+	return json.Unmarshal(b, v)
+}
+
+// ToolResult represents the result of a tool execution
+type ToolResult struct {
+	ID      string // Tool call ID (for correlation)
+	Value   any    // Structured result (optional)
+	Content string // Tool execution result (JSON string), shown to the model
+	// Refused names the reason a guardrail blocked the call before it ran
+	// ("max_steps", "loop", "approval"); empty when the call executed. A
+	// tool wrapper can switch on it to build reliability tooling — react to
+	// a detected loop, audit refusals — without parsing the message.
+	Refused string `json:"refused,omitempty"`
+}
+
+// Refusal reason codes set on ToolResult.Refused by the agent's guardrails.
+const (
+	RefusedMaxSteps = "max_steps"
+	RefusedLoop     = "loop"
+	RefusedApproval = "approval"
+)
+
+// RunInfo describes the agent run a tool call belongs to. The agent
+// attaches it to the context passed to a ToolHandler, so a wrapper can
+// correlate calls within a run and across delegation without coupling to
+// the agent package. Per-call detail (tool name, id) is on the ToolCall;
+// step and attempt counts are naturally counted by the wrapper itself.
+type RunInfo struct {
+	RunID    string // correlation id for this agent run (one per Ask)
+	ParentID string // the run that delegated to this one, if any
+	Agent    string // the agent's name
+}
+
+type runInfoKey struct{}
+
+// WithRunInfo attaches run info to ctx.
+func WithRunInfo(ctx context.Context, r RunInfo) context.Context {
+	return context.WithValue(ctx, runInfoKey{}, r)
+}
+
+// RunInfoFrom returns the run info attached to ctx, and whether it was set.
+func RunInfoFrom(ctx context.Context) (RunInfo, bool) {
+	r, ok := ctx.Value(runInfoKey{}).(RunInfo)
+	return r, ok
+}
+
+// Stream is the interface for streaming responses (future implementation)
+type Stream interface {
+	// Recv receives the next chunk of the response
+	Recv() (*Response, error)
+	// Close closes the stream
+	Close() error
+}
+
+// ToolHandler executes a tool call and returns its result. It mirrors a
+// go-micro RPC handler — context first, a request in, a result out — so
+// the same mental model carries over from services to tools.
+type ToolHandler func(ctx context.Context, call ToolCall) ToolResult
+
+// ToolWrapper wraps a ToolHandler to add behavior around execution —
+// logging, metrics, retries, guardrails. It is the tool-side analog of
+// client.CallWrapper and server.HandlerWrapper: a wrapper takes the next
+// handler and returns a new one, and code before the next(...) call runs
+// before the tool, code after runs after.
+type ToolWrapper func(ToolHandler) ToolHandler
+
+// NewFunc creates a new Model instance
+type NewFunc func(...Option) Model
+
+var providers = make(map[string]NewFunc)
+
+// Register registers a model provider
+func Register(name string, fn NewFunc) {
+	providers[name] = fn
+}
+
+// New creates a new Model instance based on the provider name
+func New(provider string, opts ...Option) Model {
+	if fn, ok := providers[provider]; ok {
+		return fn(opts...)
+	}
+
+	// Default to first registered provider
+	if len(providers) > 0 {
+		for _, fn := range providers {
+			return fn(opts...)
+		}
+	}
+
+	return nil
+}
+
+// AutoDetectProvider attempts to detect the provider from the base URL
+func AutoDetectProvider(baseURL string) string {
+	if baseURL == "" {
+		return "openai"
+	}
+	switch {
+	case strings.Contains(baseURL, "anthropic"):
+		return "anthropic"
+	case strings.Contains(baseURL, "atlascloud"):
+		return "atlascloud"
+	case strings.Contains(baseURL, "googleapis.com"), strings.Contains(baseURL, "google"):
+		return "gemini"
+	case strings.Contains(baseURL, "groq"):
+		return "groq"
+	case strings.Contains(baseURL, "mistral"):
+		return "mistral"
+	case strings.Contains(baseURL, "together"):
+		return "together"
+	default:
+		return "openai"
+	}
+}
+
+// DefaultModel is a default model instance
+var DefaultModel Model
+
+// Generate generates a response using the default model.
+func Generate(ctx context.Context, req *Request, opts ...GenerateOption) (*Response, error) {
+	if DefaultModel == nil {
+		return nil, nil
+	}
+	return DefaultModel.Generate(ctx, req, opts...)
+}

ai/openai/openai.go

@@ -0,0 +1,297 @@
+// Package openai implements the OpenAI model provider
+package openai
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"go-micro.dev/v6/ai"
+)
+
+func init() {
+	ai.Register("openai", func(opts ...ai.Option) ai.Model {
+		return NewProvider(opts...)
+	})
+	ai.RegisterImage("openai", func(opts ...ai.Option) ai.ImageModel {
+		return NewProvider(opts...)
+	})
+}
+
+// Provider implements the ai.Model interface for OpenAI
+type Provider struct {
+	opts ai.Options
+}
+
+// NewProvider creates a new OpenAI provider
+func NewProvider(opts ...ai.Option) *Provider {
+	options := ai.NewOptions(opts...)
+
+	// Set defaults if not provided
+	if options.Model == "" {
+		options.Model = "gpt-4o"
+	}
+	if options.BaseURL == "" {
+		options.BaseURL = "https://api.openai.com"
+	}
+
+	return &Provider{
+		opts: options,
+	}
+}
+
+// Init initializes the provider with options
+func (p *Provider) Init(opts ...ai.Option) error {
+	for _, o := range opts {
+		o(&p.opts)
+	}
+	return nil
+}
+
+// Options returns the provider options
+func (p *Provider) Options() ai.Options {
+	return p.opts
+}
+
+// String returns the provider name
+func (p *Provider) String() string {
+	return "openai"
+}
+
+// Generate generates a response from the model
+func (p *Provider) Generate(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (*ai.Response, error) {
+	// Build tools for OpenAI format
+	var openaiTools []map[string]any
+	for _, t := range req.Tools {
+		openaiTools = append(openaiTools, map[string]any{
+			"type": "function",
+			"function": map[string]any{
+				"name":        t.Name,
+				"description": t.Description,
+				"parameters": map[string]any{
+					"type":       "object",
+					"properties": t.Properties,
+				},
+			},
+		})
+	}
+
+	// Build messages
+	messages := []map[string]any{
+		{"role": "system", "content": req.SystemPrompt},
+		{"role": "user", "content": req.Prompt},
+	}
+
+	// Build initial request
+	apiReq := map[string]any{
+		"model":    p.opts.Model,
+		"messages": messages,
+	}
+
+	if len(openaiTools) > 0 {
+		apiReq["tools"] = openaiTools
+	}
+
+	// Make API call
+	resp, rawMessage, err := p.callAPI(ctx, apiReq)
+	if err != nil {
+		return nil, err
+	}
+
+	// If no tool calls, return response
+	if len(resp.ToolCalls) == 0 {
+		return resp, nil
+	}
+
+	// If tool handler is provided, execute tools and get final answer
+	if p.opts.ToolHandler != nil {
+		// Build follow-up messages
+		followUpMessages := append(messages, map[string]any{
+			"role":       "assistant",
+			"content":    rawMessage["content"],
+			"tool_calls": rawMessage["tool_calls"],
+		})
+
+		for _, tc := range resp.ToolCalls {
+			content := p.opts.ToolHandler(ctx, tc).Content
+			followUpMessages = append(followUpMessages, map[string]any{
+				"role":         "tool",
+				"tool_call_id": tc.ID,
+				"content":      content,
+			})
+		}
+
+		followUpReq := map[string]any{
+			"model":    p.opts.Model,
+			"messages": followUpMessages,
+		}
+
+		// Make follow-up API call
+		followUpResp, _, err := p.callAPI(ctx, followUpReq)
+		if err == nil && followUpResp.Reply != "" {
+			resp.Answer = followUpResp.Reply
+		}
+	}
+
+	return resp, nil
+}
+
+// Stream generates a streaming response (not yet implemented)
+func (p *Provider) Stream(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (ai.Stream, error) {
+	return nil, fmt.Errorf("streaming not yet implemented for openai provider")
+}
+
+// callAPI makes an HTTP request to the OpenAI API
+func (p *Provider) callAPI(ctx context.Context, req map[string]any) (*ai.Response, map[string]any, error) {
+	// Marshal request
+	reqBody, err := json.Marshal(req)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	// Build HTTP request
+	apiURL := strings.TrimRight(p.opts.BaseURL, "/") + "/v1/chat/completions"
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, bytes.NewReader(reqBody))
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	// Set headers
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("Authorization", "Bearer "+p.opts.APIKey)
+
+	// Make request
+	httpResp, err := http.DefaultClient.Do(httpReq)
+	if err != nil {
+		return nil, nil, fmt.Errorf("API request failed: %w", err)
+	}
+	defer httpResp.Body.Close()
+
+	// Read response
+	respBody, _ := io.ReadAll(httpResp.Body)
+	if httpResp.StatusCode != http.StatusOK {
+		return nil, nil, fmt.Errorf("API error (%s): %s", httpResp.Status, string(respBody))
+	}
+
+	// Parse response
+	var chatResp struct {
+		Choices []struct {
+			Message struct {
+				Content   string `json:"content"`
+				ToolCalls []struct {
+					ID       string `json:"id"`
+					Function struct {
+						Name      string `json:"name"`
+						Arguments string `json:"arguments"`
+					} `json:"function"`
+				} `json:"tool_calls"`
+			} `json:"message"`
+		} `json:"choices"`
+	}
+
+	if err := json.Unmarshal(respBody, &chatResp); err != nil {
+		return nil, nil, fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	if len(chatResp.Choices) == 0 {
+		return nil, nil, fmt.Errorf("no response from API")
+	}
+
+	choice := chatResp.Choices[0]
+	response := &ai.Response{
+		Reply: choice.Message.Content,
+	}
+
+	// Extract tool calls
+	for _, tc := range choice.Message.ToolCalls {
+		var input map[string]any
+		if err := json.Unmarshal([]byte(tc.Function.Arguments), &input); err != nil {
+			input = map[string]any{}
+		}
+		response.ToolCalls = append(response.ToolCalls, ai.ToolCall{
+			ID:    tc.ID,
+			Name:  tc.Function.Name,
+			Input: input,
+		})
+	}
+
+	// Return raw message for potential follow-up
+	rawMessage := map[string]any{
+		"content":    choice.Message.Content,
+		"tool_calls": choice.Message.ToolCalls,
+	}
+
+	return response, rawMessage, nil
+}
+
+const defaultImageModel = "gpt-image-1"
+
+func (p *Provider) GenerateImage(ctx context.Context, req *ai.ImageRequest, opts ...ai.GenerateOption) (*ai.ImageResponse, error) {
+	model := req.Model
+	if model == "" {
+		model = defaultImageModel
+	}
+	n := req.N
+	if n <= 0 {
+		n = 1
+	}
+
+	apiReq := map[string]any{
+		"model":  model,
+		"prompt": req.Prompt,
+		"n":      n,
+	}
+	if req.Size != "" {
+		apiReq["size"] = req.Size
+	}
+
+	reqBody, err := json.Marshal(apiReq)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	apiURL := strings.TrimRight(p.opts.BaseURL, "/") + "/v1/images/generations"
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, bytes.NewReader(reqBody))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("Authorization", "Bearer "+p.opts.APIKey)
+
+	httpResp, err := http.DefaultClient.Do(httpReq)
+	if err != nil {
+		return nil, fmt.Errorf("API request failed: %w", err)
+	}
+	defer httpResp.Body.Close()
+
+	respBody, _ := io.ReadAll(httpResp.Body)
+	if httpResp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("API error (%s): %s", httpResp.Status, string(respBody))
+	}
+
+	var imgResp struct {
+		Data []struct {
+			URL     string `json:"url"`
+			B64JSON string `json:"b64_json"`
+		} `json:"data"`
+	}
+
+	if err := json.Unmarshal(respBody, &imgResp); err != nil {
+		return nil, fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	response := &ai.ImageResponse{}
+	for _, d := range imgResp.Data {
+		response.Images = append(response.Images, ai.Image{
+			URL:    d.URL,
+			Base64: d.B64JSON,
+		})
+	}
+
+	return response, nil
+}

ai/openai/openai_test.go

@@ -0,0 +1,116 @@
+package openai
+
+import (
+	"context"
+	"testing"
+
+	"go-micro.dev/v6/ai"
+)
+
+func TestProvider_String(t *testing.T) {
+	p := NewProvider()
+	if p.String() != "openai" {
+		t.Errorf("Expected provider name 'openai', got '%s'", p.String())
+	}
+}
+
+func TestProvider_Init(t *testing.T) {
+	p := NewProvider()
+
+	err := p.Init(
+		ai.WithModel("test-model"),
+		ai.WithAPIKey("test-key"),
+		ai.WithBaseURL("https://test.com"),
+	)
+
+	if err != nil {
+		t.Fatalf("Init failed: %v", err)
+	}
+
+	opts := p.Options()
+	if opts.Model != "test-model" {
+		t.Errorf("Expected model 'test-model', got '%s'", opts.Model)
+	}
+	if opts.APIKey != "test-key" {
+		t.Errorf("Expected API key 'test-key', got '%s'", opts.APIKey)
+	}
+	if opts.BaseURL != "https://test.com" {
+		t.Errorf("Expected base URL 'https://test.com', got '%s'", opts.BaseURL)
+	}
+}
+
+func TestProvider_Options(t *testing.T) {
+	p := NewProvider(
+		ai.WithModel("custom-model"),
+		ai.WithAPIKey("my-key"),
+	)
+
+	opts := p.Options()
+	if opts.Model != "custom-model" {
+		t.Errorf("Expected model 'custom-model', got '%s'", opts.Model)
+	}
+	if opts.APIKey != "my-key" {
+		t.Errorf("Expected API key 'my-key', got '%s'", opts.APIKey)
+	}
+}
+
+func TestProvider_Defaults(t *testing.T) {
+	p := NewProvider()
+
+	opts := p.Options()
+	if opts.Model != "gpt-4o" {
+		t.Errorf("Expected default model 'gpt-4o', got '%s'", opts.Model)
+	}
+	if opts.BaseURL != "https://api.openai.com" {
+		t.Errorf("Expected default base URL 'https://api.openai.com', got '%s'", opts.BaseURL)
+	}
+}
+
+func TestProvider_Generate_NoAPIKey(t *testing.T) {
+	p := NewProvider()
+
+	req := &ai.Request{
+		Prompt:       "Hello",
+		SystemPrompt: "You are helpful",
+	}
+
+	_, err := p.Generate(context.Background(), req)
+	if err == nil {
+		t.Error("Expected error when API key is missing, got nil")
+	}
+}
+
+func TestProvider_Stream_NotImplemented(t *testing.T) {
+	p := NewProvider()
+
+	req := &ai.Request{
+		Prompt: "Hello",
+	}
+
+	_, err := p.Stream(context.Background(), req)
+	if err == nil {
+		t.Error("Expected error for unimplemented streaming, got nil")
+	}
+}
+
+func TestProvider_ImageRegistration(t *testing.T) {
+	ig := ai.NewImage("openai", ai.WithAPIKey("test"))
+	if ig == nil {
+		t.Fatal("ai.NewImage('openai') returned nil — image provider not registered")
+	}
+	if ig.String() != "openai" {
+		t.Errorf("Expected 'openai', got '%s'", ig.String())
+	}
+}
+
+func TestProvider_GenerateImage_NoAPIKey(t *testing.T) {
+	p := NewProvider()
+	_, err := p.GenerateImage(context.Background(), &ai.ImageRequest{Prompt: "a cat"})
+	if err == nil {
+		t.Error("Expected error when API key is missing, got nil")
+	}
+}
+
+func TestProvider_ImplementsImageModel(t *testing.T) {
+	var _ ai.ImageModel = (*Provider)(nil)
+}

ai/options.go

@@ -0,0 +1,93 @@
+package ai
+
+import (
+	"context"
+)
+
+// Options for model configuration
+type Options struct {
+	// Context for the model
+	Context context.Context
+	// Model name (e.g., "gpt-4o", "claude-sonnet-4-20250514")
+	Model string
+	// APIKey for authentication
+	APIKey string
+	// BaseURL for the API endpoint
+	BaseURL string
+	// ToolHandler handles tool calls (optional, for automatic tool execution)
+	ToolHandler ToolHandler
+}
+
+// GenerateOptions for generate call
+type GenerateOptions struct {
+	// Context for this specific generate call
+	Context context.Context
+}
+
+// Option is a function that modifies Options
+type Option func(*Options)
+
+// GenerateOption is a function that modifies GenerateOptions
+type GenerateOption func(*GenerateOptions)
+
+// NewOptions creates new Options with defaults
+func NewOptions(opts ...Option) Options {
+	options := Options{
+		Context: context.Background(),
+	}
+	for _, o := range opts {
+		o(&options)
+	}
+	return options
+}
+
+// WithModel sets the model name
+func WithModel(m string) Option {
+	return func(o *Options) {
+		o.Model = m
+	}
+}
+
+// WithAPIKey sets the API key
+func WithAPIKey(key string) Option {
+	return func(o *Options) {
+		o.APIKey = key
+	}
+}
+
+// WithBaseURL sets the base URL
+func WithBaseURL(url string) Option {
+	return func(o *Options) {
+		o.BaseURL = url
+	}
+}
+
+// WithContext sets the context
+func WithContext(ctx context.Context) Option {
+	return func(o *Options) {
+		o.Context = ctx
+	}
+}
+
+// WithToolHandler sets the tool handler
+func WithToolHandler(handler ToolHandler) Option {
+	return func(o *Options) {
+		o.ToolHandler = handler
+	}
+}
+
+// WithTools wires a Tools instance into the model, setting the tool
+// handler so the model can execute discovered service endpoints. The
+// tool list itself is passed per-request via Request.Tools.
+//
+//	tools := ai.NewTools(service.Registry())
+//	list, _ := tools.Discover()
+//	m := ai.New("anthropic", ai.WithAPIKey(key), ai.WithTools(tools))
+//	resp, _ := m.Generate(ctx, &ai.Request{Prompt: input, Tools: list})
+func WithTools(t *Tools) Option {
+	return func(o *Options) {
+		if t != nil {
+			o.ToolHandler = t.Handler()
+		}
+	}
+}

ai/together/together.go

@@ -0,0 +1,194 @@
+// Package together implements the Together AI model provider.
+//
+// Together AI provides fast inference for open-weight models via an
+// OpenAI-compatible chat completions endpoint.
+//
+// Usage:
+//
+//	import _ "go-micro.dev/v6/ai/together"
+//
+//	m := ai.New("together",
+//	    ai.WithAPIKey("your-api-key"),
+//	)
+package together
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"go-micro.dev/v6/ai"
+)
+
+func init() {
+	ai.Register("together", func(opts ...ai.Option) ai.Model {
+		return NewProvider(opts...)
+	})
+}
+
+type Provider struct {
+	opts ai.Options
+}
+
+func NewProvider(opts ...ai.Option) *Provider {
+	options := ai.NewOptions(opts...)
+	if options.Model == "" {
+		options.Model = "meta-llama/Llama-3.3-70B-Instruct-Turbo"
+	}
+	if options.BaseURL == "" {
+		options.BaseURL = "https://api.together.xyz"
+	}
+	return &Provider{opts: options}
+}
+
+func (p *Provider) Init(opts ...ai.Option) error {
+	for _, o := range opts {
+		o(&p.opts)
+	}
+	return nil
+}
+
+func (p *Provider) Options() ai.Options { return p.opts }
+func (p *Provider) String() string      { return "together" }
+
+func (p *Provider) Generate(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (*ai.Response, error) {
+	var tools []map[string]any
+	for _, t := range req.Tools {
+		tools = append(tools, map[string]any{
+			"type": "function",
+			"function": map[string]any{
+				"name":        t.Name,
+				"description": t.Description,
+				"parameters": map[string]any{
+					"type":       "object",
+					"properties": t.Properties,
+				},
+			},
+		})
+	}
+
+	messages := []map[string]any{
+		{"role": "system", "content": req.SystemPrompt},
+		{"role": "user", "content": req.Prompt},
+	}
+
+	apiReq := map[string]any{
+		"model":    p.opts.Model,
+		"messages": messages,
+	}
+	if len(tools) > 0 {
+		apiReq["tools"] = tools
+	}
+
+	resp, rawMessage, err := p.callAPI(ctx, apiReq)
+	if err != nil {
+		return nil, err
+	}
+	if len(resp.ToolCalls) == 0 {
+		return resp, nil
+	}
+
+	if p.opts.ToolHandler != nil {
+		followUpMessages := append(messages, map[string]any{
+			"role":       "assistant",
+			"content":    rawMessage["content"],
+			"tool_calls": rawMessage["tool_calls"],
+		})
+		for _, tc := range resp.ToolCalls {
+			content := p.opts.ToolHandler(ctx, tc).Content
+			followUpMessages = append(followUpMessages, map[string]any{
+				"role":         "tool",
+				"tool_call_id": tc.ID,
+				"content":      content,
+			})
+		}
+		followUpResp, _, err := p.callAPI(ctx, map[string]any{
+			"model":    p.opts.Model,
+			"messages": followUpMessages,
+		})
+		if err == nil && followUpResp.Reply != "" {
+			resp.Answer = followUpResp.Reply
+		}
+	}
+
+	return resp, nil
+}
+
+func (p *Provider) Stream(ctx context.Context, req *ai.Request, opts ...ai.GenerateOption) (ai.Stream, error) {
+	return nil, fmt.Errorf("streaming not yet implemented for together provider")
+}
+
+func (p *Provider) callAPI(ctx context.Context, req map[string]any) (*ai.Response, map[string]any, error) {
+	reqBody, err := json.Marshal(req)
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	apiURL := strings.TrimRight(p.opts.BaseURL, "/") + "/v1/chat/completions"
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, bytes.NewReader(reqBody))
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("Authorization", "Bearer "+p.opts.APIKey)
+
+	httpResp, err := http.DefaultClient.Do(httpReq)
+	if err != nil {
+		return nil, nil, fmt.Errorf("API request failed: %w", err)
+	}
+	defer httpResp.Body.Close()
+
+	respBody, _ := io.ReadAll(httpResp.Body)
+	if httpResp.StatusCode != http.StatusOK {
+		return nil, nil, fmt.Errorf("API error (%s): %s", httpResp.Status, string(respBody))
+	}
+
+	var chatResp struct {
+		Choices []struct {
+			Message struct {
+				Content   string `json:"content"`
+				ToolCalls []struct {
+					ID       string `json:"id"`
+					Function struct {
+						Name      string `json:"name"`
+						Arguments string `json:"arguments"`
+					} `json:"function"`
+				} `json:"tool_calls"`
+			} `json:"message"`
+		} `json:"choices"`
+	}
+
+	if err := json.Unmarshal(respBody, &chatResp); err != nil {
+		return nil, nil, fmt.Errorf("failed to parse response: %w", err)
+	}
+	if len(chatResp.Choices) == 0 {
+		return nil, nil, fmt.Errorf("no response from API")
+	}
+
+	choice := chatResp.Choices[0]
+	response := &ai.Response{Reply: choice.Message.Content}
+
+	for _, tc := range choice.Message.ToolCalls {
+		var input map[string]any
+		if err := json.Unmarshal([]byte(tc.Function.Arguments), &input); err != nil {
+			input = map[string]any{}
+		}
+		response.ToolCalls = append(response.ToolCalls, ai.ToolCall{
+			ID:    tc.ID,
+			Name:  tc.Function.Name,
+			Input: input,
+		})
+	}
+
+	rawMessage := map[string]any{
+		"content":    choice.Message.Content,
+		"tool_calls": choice.Message.ToolCalls,
+	}
+
+	return response, rawMessage, nil
+}

ai/together/together_test.go

@@ -0,0 +1,56 @@
+package together
+
+import (
+	"context"
+	"testing"
+
+	"go-micro.dev/v6/ai"
+)
+
+func TestProvider_String(t *testing.T) {
+	if NewProvider().String() != "together" {
+		t.Errorf("got %q", NewProvider().String())
+	}
+}
+
+func TestProvider_Defaults(t *testing.T) {
+	opts := NewProvider().Options()
+	if opts.Model != "meta-llama/Llama-3.3-70B-Instruct-Turbo" {
+		t.Errorf("default model = %q", opts.Model)
+	}
+	if opts.BaseURL != "https://api.together.xyz" {
+		t.Errorf("default base URL = %q", opts.BaseURL)
+	}
+}
+
+func TestProvider_Init(t *testing.T) {
+	p := NewProvider()
+	if err := p.Init(ai.WithModel("m"), ai.WithAPIKey("k")); err != nil {
+		t.Fatal(err)
+	}
+	if p.Options().Model != "m" || p.Options().APIKey != "k" {
+		t.Error("Init did not apply options")
+	}
+}
+
+func TestProvider_Generate_NoAPIKey(t *testing.T) {
+	if _, err := NewProvider().Generate(context.Background(), &ai.Request{Prompt: "hi"}); err == nil {
+		t.Error("expected error without API key")
+	}
+}
+
+func TestProvider_Stream_NotImplemented(t *testing.T) {
+	if _, err := NewProvider().Stream(context.Background(), &ai.Request{Prompt: "hi"}); err == nil {
+		t.Error("expected error")
+	}
+}
+
+func TestProvider_Registration(t *testing.T) {
+	m := ai.New("together", ai.WithAPIKey("test"))
+	if m == nil {
+		t.Fatal("provider not registered")
+	}
+	if m.String() != "together" {
+		t.Errorf("got %q", m.String())
+	}
+}

ai/tools.go

@@ -0,0 +1,185 @@
+package ai
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"sync"
+
+	"go-micro.dev/v6/client"
+	codecBytes "go-micro.dev/v6/codec/bytes"
+	"go-micro.dev/v6/registry"
+)
+
+type toolNameMap struct {
+	mu sync.RWMutex
+	m  map[string]string
+}
+
+func (n *toolNameMap) put(safe, original string) {
+	n.mu.Lock()
+	n.m[safe] = original
+	n.mu.Unlock()
+}
+
+func (n *toolNameMap) get(safe string) (string, bool) {
+	n.mu.RLock()
+	v, ok := n.m[safe]
+	n.mu.RUnlock()
+	return v, ok
+}
+
+// Tools discovers go-micro services from a registry and converts their
+// endpoints into Tool definitions. It also executes tool calls via RPC.
+//
+// Create with NewTools, discover the tool list with Discover, and wire
+// execution into a model with WithTools:
+//
+//	tools := ai.NewTools(service.Registry())
+//	list, _ := tools.Discover()
+//	m := ai.New("anthropic", ai.WithAPIKey(key), ai.WithTools(tools))
+//	resp, _ := m.Generate(ctx, &ai.Request{Prompt: input, Tools: list})
+type Tools struct {
+	registry registry.Registry
+	client   client.Client
+	names    *toolNameMap
+}
+
+// ToolOption configures a Tools instance.
+type ToolOption func(*Tools)
+
+// ToolClient sets the client used to execute tool calls. Defaults to
+// client.DefaultClient.
+func ToolClient(c client.Client) ToolOption {
+	return func(t *Tools) {
+		if c != nil {
+			t.client = c
+		}
+	}
+}
+
+// NewTools creates a Tools bound to the given registry.
+func NewTools(reg registry.Registry, opts ...ToolOption) *Tools {
+	t := &Tools{
+		registry: reg,
+		client:   client.DefaultClient,
+		names:    &toolNameMap{m: map[string]string{}},
+	}
+	for _, o := range opts {
+		o(t)
+	}
+	return t
+}
+
+// Discover walks the registry and returns one Tool per service
+// endpoint. Tool names are LLM-safe (dots replaced with underscores).
+func (t *Tools) Discover() ([]Tool, error) {
+	services, err := t.registry.ListServices()
+	if err != nil {
+		return nil, err
+	}
+
+	var out []Tool
+	for _, svc := range services {
+		full, err := t.registry.GetService(svc.Name)
+		if err != nil || len(full) == 0 {
+			continue
+		}
+		for _, ep := range full[0].Endpoints {
+			original := fmt.Sprintf("%s.%s", svc.Name, ep.Name)
+			safe := strings.ReplaceAll(original, ".", "_")
+			t.names.put(safe, original)
+
+			desc := fmt.Sprintf("Call %s on %s service", ep.Name, svc.Name)
+			if ep.Metadata != nil {
+				if d, ok := ep.Metadata["description"]; ok && d != "" {
+					desc = d
+				}
+			}
+
+			props := map[string]any{}
+			if ep.Request != nil {
+				for _, field := range ep.Request.Values {
+					props[field.Name] = map[string]any{
+						"type":        toolJSONType(field.Type),
+						"description": fmt.Sprintf("%s (%s)", field.Name, field.Type),
+					}
+				}
+			}
+
+			out = append(out, Tool{
+				Name:         safe,
+				OriginalName: original,
+				Description:  desc,
+				Properties:   props,
+			})
+		}
+	}
+
+	return out, nil
+}
+
+// Handler returns a ToolHandler that executes tool calls via RPC using
+// the configured client. Tool names may be LLM-safe (underscored) or
+// original (dotted). WithTools uses this internally.
+func (t *Tools) Handler() ToolHandler {
+	c := t.client
+	if c == nil {
+		c = client.DefaultClient
+	}
+	return func(ctx context.Context, call ToolCall) ToolResult {
+		name := call.Name
+		if orig, ok := t.names.get(name); ok {
+			name = orig
+		}
+		parts := strings.SplitN(name, ".", 2)
+		if len(parts) != 2 {
+			return toolErrResult(call.ID, "invalid tool name: "+name)
+		}
+
+		inputBytes, err := json.Marshal(call.Input)
+		if err != nil {
+			return toolErrResult(call.ID, "failed to marshal input: "+err.Error())
+		}
+
+		req := c.NewRequest(parts[0], parts[1], &codecBytes.Frame{Data: inputBytes})
+		var rsp codecBytes.Frame
+		if err := c.Call(ctx, req, &rsp); err != nil {
+			return toolErrResult(call.ID, err.Error())
+		}
+
+		var result any
+		if err := json.Unmarshal(rsp.Data, &result); err != nil {
+			result = string(rsp.Data)
+		}
+		return ToolResult{ID: call.ID, Value: result, Content: string(rsp.Data)}
+	}
+}
+
+// DiscoverTools is a convenience that discovers tools from a registry
+// without creating a Tools instance. For paired discovery + execution,
+// create a Tools with NewTools instead.
+func DiscoverTools(reg registry.Registry) ([]Tool, error) {
+	return NewTools(reg).Discover()
+}
+
+func toolErrResult(id, msg string) ToolResult {
+	encoded, _ := json.Marshal(map[string]string{"error": msg})
+	return ToolResult{ID: id, Value: map[string]string{"error": msg}, Content: string(encoded)}
+}
+
+func toolJSONType(goType string) string {
+	switch goType {
+	case "string":
+		return "string"
+	case "int", "int32", "int64", "uint", "uint32", "uint64":
+		return "integer"
+	case "float32", "float64":
+		return "number"
+	case "bool":
+		return "boolean"
+	default:
+		return "object"
+	}
+}

ai/tools_test.go

@@ -0,0 +1,116 @@
+package ai
+
+import (
+	"context"
+	"testing"
+
+	"go-micro.dev/v6/registry"
+)
+
+func TestToolJSONType(t *testing.T) {
+	cases := map[string]string{
+		"string":  "string",
+		"int":     "integer",
+		"int64":   "integer",
+		"float64": "number",
+		"bool":    "boolean",
+		"User":    "object",
+		"":        "object",
+	}
+	for in, want := range cases {
+		if got := toolJSONType(in); got != want {
+			t.Errorf("toolJSONType(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestDiscoverTools_Empty(t *testing.T) {
+	reg := registry.NewMemoryRegistry()
+	tools, err := DiscoverTools(reg)
+	if err != nil {
+		t.Fatalf("DiscoverTools: %v", err)
+	}
+	if len(tools) != 0 {
+		t.Errorf("expected 0 tools, got %d", len(tools))
+	}
+}
+
+func TestDiscoverTools_DiscoversEndpoints(t *testing.T) {
+	reg := registry.NewMemoryRegistry()
+	svc := &registry.Service{
+		Name:    "users",
+		Version: "1.0.0",
+		Nodes: []*registry.Node{
+			{Id: "users-1", Address: "127.0.0.1:9000"},
+		},
+		Endpoints: []*registry.Endpoint{
+			{
+				Name: "Users.Get",
+				Metadata: map[string]string{
+					"description": "Fetch a user by ID",
+				},
+				Request: &registry.Value{
+					Name: "GetRequest",
+					Type: "GetRequest",
+					Values: []*registry.Value{
+						{Name: "id", Type: "string"},
+						{Name: "expand", Type: "bool"},
+					},
+				},
+			},
+		},
+	}
+	if err := reg.Register(svc); err != nil {
+		t.Fatalf("Register: %v", err)
+	}
+
+	tools, err := DiscoverTools(reg)
+	if err != nil {
+		t.Fatalf("DiscoverTools: %v", err)
+	}
+	if len(tools) != 1 {
+		t.Fatalf("expected 1 tool, got %d", len(tools))
+	}
+
+	tool := tools[0]
+	if tool.Name != "users_Users_Get" {
+		t.Errorf("safe name = %q", tool.Name)
+	}
+	if tool.OriginalName != "users.Users.Get" {
+		t.Errorf("original = %q", tool.OriginalName)
+	}
+	if tool.Description != "Fetch a user by ID" {
+		t.Errorf("description = %q", tool.Description)
+	}
+}
+
+func TestTools_HandlerResolvesSafeName(t *testing.T) {
+	tools := NewTools(registry.NewMemoryRegistry())
+	tools.names.put("users_Users_Get", "users.Users.Get")
+
+	resolved, ok := tools.names.get("users_Users_Get")
+	if !ok || resolved != "users.Users.Get" {
+		t.Errorf("name map lookup = (%q, %v)", resolved, ok)
+	}
+}
+
+func TestTools_HandlerInvalidName(t *testing.T) {
+	tools := NewTools(registry.NewMemoryRegistry())
+	h := tools.Handler()
+
+	res := h(context.Background(), ToolCall{Name: "foo", Input: map[string]any{}})
+	if res.Value == nil {
+		t.Fatal("expected error result")
+	}
+	if res.Content == "" {
+		t.Error("expected non-empty content")
+	}
+}
+
+func TestWithTools(t *testing.T) {
+	tools := NewTools(registry.NewMemoryRegistry())
+	opts := NewOptions(WithTools(tools))
+	if opts.ToolHandler == nil {
+		t.Error("WithTools did not set a ToolHandler")
+	}
+}

ai/video.go

@@ -0,0 +1,51 @@
+package ai
+
+import "context"
+
+// VideoModel provides an interface for video generation providers.
+// Providers that support video generation implement this alongside
+// Model and/or ImageModel.
+type VideoModel interface {
+	GenerateVideo(ctx context.Context, req *VideoRequest, opts ...GenerateOption) (*VideoResponse, error)
+	String() string
+}
+
+// VideoRequest describes what video to generate.
+type VideoRequest struct {
+	// Prompt is the text description or instructions for the video.
+	Prompt string
+	// Model overrides the provider's default video model.
+	Model string
+	// Images are reference image URLs for image-to-video generation.
+	Images []string
+	// Duration in seconds. Provider-specific defaults apply.
+	Duration int
+	// AspectRatio (e.g. "16:9", "9:16"). Provider-specific.
+	AspectRatio string
+	// Resolution (e.g. "720p", "1080p"). Provider-specific.
+	Resolution string
+}
+
+// VideoResponse holds the generated video.
+type VideoResponse struct {
+	// URL is the remote URL where the video can be fetched.
+	URL string
+}
+
+// NewVideoFunc creates a new VideoModel instance.
+type NewVideoFunc func(...Option) VideoModel
+
+var videoProviders = make(map[string]NewVideoFunc)
+
+// RegisterVideo registers a video generation provider.
+func RegisterVideo(name string, fn NewVideoFunc) {
+	videoProviders[name] = fn
+}
+
+// NewVideo creates a new VideoModel instance based on the provider name.
+func NewVideo(provider string, opts ...Option) VideoModel {
+	if fn, ok := videoProviders[provider]; ok {
+		return fn(opts...)
+	}
+	return nil
+}

auth/jwt/jwt.go

@@ -4,9 +4,9 @@ import (
 	"sync"
 	"time"
 
-	jwtToken "github.com/micro/plugins/v5/auth/jwt/token"
-	"go-micro.dev/v5/auth"
-	"go-micro.dev/v5/cmd"
+	"go-micro.dev/v6/auth"
+	jwtToken "go-micro.dev/v6/auth/jwt/token"
+	"go-micro.dev/v6/cmd"
 )
 
 func init() {

auth/jwt/token/jwt.go

@@ -4,8 +4,8 @@ import (
 	"encoding/base64"
 	"time"
 
-	"github.com/dgrijalva/jwt-go"
-	"go-micro.dev/v5/auth"
+	"github.com/golang-jwt/jwt/v5"
+	"go-micro.dev/v6/auth"
 )
 
 // authClaims to be encoded in the JWT.
@@ -14,7 +14,7 @@ type authClaims struct {
 	Scopes   []string          `json:"scopes"`
 	Metadata map[string]string `json:"metadata"`
 
-	jwt.StandardClaims
+	jwt.RegisteredClaims
 }
 
 // JWT implementation of token provider.
@@ -49,10 +49,10 @@ func (j *JWT) Generate(acc *auth.Account, opts ...GenerateOption) (*Token, error
 	// generate the JWT
 	expiry := time.Now().Add(options.Expiry)
 	t := jwt.NewWithClaims(jwt.SigningMethodRS256, authClaims{
-		acc.Type, acc.Scopes, acc.Metadata, jwt.StandardClaims{
+		acc.Type, acc.Scopes, acc.Metadata, jwt.RegisteredClaims{
 			Subject:   acc.ID,
 			Issuer:    acc.Issuer,
-			ExpiresAt: expiry.Unix(),
+			ExpiresAt: jwt.NewNumericDate(expiry),
 		},
 	})
 	tok, err := t.SignedString(key)

auth/jwt/token/jwt_test.go

@@ -5,7 +5,7 @@ import (
 	"testing"
 	"time"
 
-	"go-micro.dev/v5/auth"
+	"go-micro.dev/v6/auth"
 )
 
 func TestGenerate(t *testing.T) {

auth/jwt/token/options.go

@@ -3,7 +3,7 @@ package token
 import (
 	"time"
 
-	"go-micro.dev/v5/store"
+	"go-micro.dev/v6/store"
 )
 
 type Options struct {

auth/jwt/token/token.go

@@ -4,7 +4,7 @@ import (
 	"errors"
 	"time"
 
-	"go-micro.dev/v5/auth"
+	"go-micro.dev/v6/auth"
 )
 
 var (

auth/noop/noop.go

@@ -14,7 +14,7 @@
 package noop
 
 import (
-	"go-micro.dev/v5/auth"
+	"go-micro.dev/v6/auth"
 )
 
 // NewAuth returns a new noop auth provider.

auth/options.go

@@ -4,7 +4,7 @@ import (
 	"context"
 	"time"
 
-	"go-micro.dev/v5/logger"
+	"go-micro.dev/v6/logger"
 )
 
 func NewOptions(opts ...Option) Options {

broker/http.go

@@ -15,14 +15,14 @@ import (
 	"time"
 
 	"github.com/google/uuid"
-	"go-micro.dev/v5/codec/json"
-	merr "go-micro.dev/v5/errors"
-	"go-micro.dev/v5/registry"
-	"go-micro.dev/v5/registry/cache"
-	"go-micro.dev/v5/transport/headers"
-	maddr "go-micro.dev/v5/util/addr"
-	mnet "go-micro.dev/v5/util/net"
-	mls "go-micro.dev/v5/util/tls"
+	"go-micro.dev/v6/codec/json"
+	merr "go-micro.dev/v6/errors"
+	maddr "go-micro.dev/v6/internal/util/addr"
+	mnet "go-micro.dev/v6/internal/util/net"
+	mls "go-micro.dev/v6/internal/util/tls"
+	"go-micro.dev/v6/registry"
+	"go-micro.dev/v6/registry/cache"
+	"go-micro.dev/v6/transport/headers"
 	"golang.org/x/net/http2"
 )
 
@@ -100,7 +100,7 @@ func newTransport(config *tls.Config) *http.Transport {
 	})
 
 	// setup http2
-	http2.ConfigureTransport(t)
+	_ = http2.ConfigureTransport(t)
 
 	return t
 }
@@ -288,19 +288,19 @@ func (h *httpBroker) run(l net.Listener) {
 }
 
 func (h *httpBroker) ServeHTTP(w http.ResponseWriter, req *http.Request) {
-	if req.Method != "POST" {
+	if req.Method != http.MethodPost {
 		err := merr.BadRequest("go.micro.broker", "Method not allowed")
 		http.Error(w, err.Error(), http.StatusMethodNotAllowed)
 		return
 	}
 	defer req.Body.Close()
 
-	req.ParseForm()
+	_ = req.ParseForm()
 
 	b, err := io.ReadAll(req.Body)
 	if err != nil {
 		errr := merr.InternalServerError("go.micro.broker", "Error reading request body: %v", err)
-		w.WriteHeader(500)
+		w.WriteHeader(http.StatusInternalServerError)
 		w.Write([]byte(errr.Error()))
 		return
 	}
@@ -308,7 +308,7 @@ func (h *httpBroker) ServeHTTP(w http.ResponseWriter, req *http.Request) {
 	var m *Message
 	if err = h.opts.Codec.Unmarshal(b, &m); err != nil {
 		errr := merr.InternalServerError("go.micro.broker", "Error parsing request body: %v", err)
-		w.WriteHeader(500)
+		w.WriteHeader(http.StatusInternalServerError)
 		w.Write([]byte(errr.Error()))
 		return
 	}
@@ -318,7 +318,7 @@ func (h *httpBroker) ServeHTTP(w http.ResponseWriter, req *http.Request) {
 
 	if len(topic) == 0 {
 		errr := merr.InternalServerError("go.micro.broker", "Topic not found")
-		w.WriteHeader(500)
+		w.WriteHeader(http.StatusInternalServerError)
 		w.Write([]byte(errr.Error()))
 		return
 	}
@@ -406,7 +406,7 @@ func (h *httpBroker) Connect() error {
 	addr := h.address
 	h.address = l.Addr().String()
 
-	go http.Serve(l, h.mux)
+	go func() { _ = http.Serve(l, h.mux) }()
 	go func() {
 		h.run(l)
 		h.Lock()
@@ -555,7 +555,7 @@ func (h *httpBroker) Publish(topic string, msg *Message, opts ...PublishOption)
 		}
 
 		// discard response body
-		io.Copy(io.Discard, r.Body)
+		_, _ = io.Copy(io.Discard, r.Body)
 		r.Body.Close()
 		return nil
 	}

broker/http_test.go

@@ -6,8 +6,8 @@ import (
 	"time"
 
 	"github.com/google/uuid"
-	"go-micro.dev/v5/broker"
-	"go-micro.dev/v5/registry"
+	"go-micro.dev/v6/broker"
+	"go-micro.dev/v6/registry"
 )
 
 var (
@@ -161,7 +161,9 @@ func pub(b *testing.B, c int) {
 		go func() {
 			for range ch {
 				if err := brk.Publish(topic, msg); err != nil {
-					b.Fatalf("Unexpected publish error: %v", err)
+					b.Errorf("Unexpected publish error: %v", err)
+					wg.Done()
+					return
 				}
 				select {
 				case <-done:

broker/memory.go

@@ -7,9 +7,9 @@ import (
 	"sync"
 
 	"github.com/google/uuid"
-	log "go-micro.dev/v5/logger"
-	maddr "go-micro.dev/v5/util/addr"
-	mnet "go-micro.dev/v5/util/net"
+	maddr "go-micro.dev/v6/internal/util/addr"
+	mnet "go-micro.dev/v6/internal/util/net"
+	log "go-micro.dev/v6/logger"
 )
 
 type memoryBroker struct {
@@ -122,7 +122,7 @@ func (m *memoryBroker) Publish(topic string, msg *Message, opts ...PublishOption
 		if err := sub.handler(p); err != nil {
 			p.err = err
 			if eh := m.opts.ErrorHandler; eh != nil {
-				eh(p)
+				_ = eh(p)
 				continue
 			}
 			return err

broker/memory_test.go

@@ -4,7 +4,7 @@ import (
 	"fmt"
 	"testing"
 
-	"go-micro.dev/v5/broker"
+	"go-micro.dev/v6/broker"
 )
 
 func TestMemoryBroker(t *testing.T) {

broker/nats/context.go

@@ -3,7 +3,7 @@ package nats
 import (
 	"context"
 
-	"go-micro.dev/v5/broker"
+	"go-micro.dev/v6/broker"
 )
 
 // setBrokerOption returns a function to setup a context with given value.

broker/nats/nats.go

@@ -9,10 +9,10 @@ import (
 	"time"
 
 	natsp "github.com/nats-io/nats.go"
-	"go-micro.dev/v5/broker"
-	"go-micro.dev/v5/codec/json"
-	"go-micro.dev/v5/logger"
-	"go-micro.dev/v5/registry"
+	"go-micro.dev/v6/broker"
+	"go-micro.dev/v6/codec/json"
+	"go-micro.dev/v6/logger"
+	"go-micro.dev/v6/registry"
 )
 
 type natsBroker struct {
@@ -194,7 +194,7 @@ func (n *natsBroker) Disconnect() error {
 	if n.conn != nil {
 		// drain the connection if specified
 		if n.drain {
-			n.conn.Drain()
+			_ = n.conn.Drain()
 			n.closeCh <- nil
 		}
 
@@ -233,7 +233,7 @@ func (n *natsBroker) Publish(topic string, msg *broker.Message, opts ...broker.P
 		if err != nil {
 			return err
 		}
-		defer n.pool.Put(poolConn)
+		defer func() { _ = n.pool.Put(poolConn) }()
 
 		conn := poolConn.Conn()
 		if conn == nil {
@@ -279,7 +279,7 @@ func (n *natsBroker) Subscribe(topic string, handler broker.Handler, opts ...bro
 			m.Body = msg.Data
 			n.opts.Logger.Log(logger.ErrorLevel, err)
 			if eh != nil {
-				eh(pub)
+				_ = eh(pub)
 			}
 			return
 		}
@@ -287,7 +287,7 @@ func (n *natsBroker) Subscribe(topic string, handler broker.Handler, opts ...bro
 			pub.err = err
 			n.opts.Logger.Log(logger.ErrorLevel, err)
 			if eh != nil {
-				eh(pub)
+				_ = eh(pub)
 			}
 		}
 	}
@@ -304,7 +304,7 @@ func (n *natsBroker) Subscribe(topic string, handler broker.Handler, opts ...bro
 
 		conn := poolConn.Conn()
 		if conn == nil {
-			n.pool.Put(poolConn)
+			_ = n.pool.Put(poolConn)
 			return nil, errors.New("invalid connection from pool")
 		}
 
@@ -315,13 +315,13 @@ func (n *natsBroker) Subscribe(topic string, handler broker.Handler, opts ...bro
 		}
 
 		if err != nil {
-			n.pool.Put(poolConn)
+			_ = n.pool.Put(poolConn)
 			return nil, err
 		}
 
 		// Return connection to pool after subscription is created
 		// The subscription keeps the connection alive
-		n.pool.Put(poolConn)
+		_ = n.pool.Put(poolConn)
 
 		return &subscriber{s: sub, opts: opt}, nil
 	}
@@ -349,7 +349,7 @@ func (n *natsBroker) setOption(opts ...broker.Option) {
 		o(&n.opts)
 	}
 
-	n.Once.Do(func() {
+	n.Do(func() {
 		n.nopts = natsp.GetDefaultOptions()
 		n.poolSize = 1 // Default to single connection (no pooling)
 		n.poolIdleTimeout = 5 * time.Minute

broker/nats/nats_test.go

@@ -5,7 +5,7 @@ import (
 	"testing"
 
 	natsp "github.com/nats-io/nats.go"
-	"go-micro.dev/v5/broker"
+	"go-micro.dev/v6/broker"
 )
 
 var addrTestCases = []struct {

broker/nats/options.go

@@ -4,7 +4,7 @@ import (
 	"time"
 
 	natsp "github.com/nats-io/nats.go"
-	"go-micro.dev/v5/broker"
+	"go-micro.dev/v6/broker"
 )
 
 type optionsKey struct{}

broker/options.go

@@ -4,9 +4,9 @@ import (
 	"context"
 	"crypto/tls"
 
-	"go-micro.dev/v5/codec"
-	"go-micro.dev/v5/logger"
-	"go-micro.dev/v5/registry"
+	"go-micro.dev/v6/codec"
+	"go-micro.dev/v6/logger"
+	"go-micro.dev/v6/registry"
 )
 
 type Options struct {

broker/rabbitmq/channel.go

@@ -61,14 +61,14 @@ func (r *rabbitMQChannel) Connect(prefetchCount int, prefetchGlobal bool, confir
 
 func (r *rabbitMQChannel) Close() error {
 	if r.channel == nil {
-		return errors.New("Channel is nil")
+		return errors.New("channel is nil")
 	}
 	return r.channel.Close()
 }
 
 func (r *rabbitMQChannel) Publish(exchange, key string, message amqp.Publishing) error {
 	if r.channel == nil {
-		return errors.New("Channel is nil")
+		return errors.New("channel is nil")
 	}
 
 	if r.confirmPublish != nil {
@@ -84,11 +84,11 @@ func (r *rabbitMQChannel) Publish(exchange, key string, message amqp.Publishing)
 	if r.confirmPublish != nil {
 		confirmation, ok := <-r.confirmPublish
 		if !ok {
-			return errors.New("Channel closed before could receive confirmation of publish")
+			return errors.New("channel closed before could receive confirmation of publish")
 		}
 
 		if !confirmation.Ack {
-			return errors.New("Could not publish message, received nack from broker on confirmation")
+			return errors.New("could not publish message, received nack from broker on confirmation")
 		}
 	}
 

broker/rabbitmq/connection.go

@@ -11,16 +11,16 @@ import (
 	"time"
 
 	amqp "github.com/rabbitmq/amqp091-go"
-	"go-micro.dev/v5/logger"
-	mtls "go-micro.dev/v5/util/tls"
+	mtls "go-micro.dev/v6/internal/util/tls"
+	"go-micro.dev/v6/logger"
 )
 
 type MQExchangeType string
 
 const (
 	ExchangeTypeFanout MQExchangeType = "fanout"
-	ExchangeTypeTopic                 = "topic"
-	ExchangeTypeDirect                = "direct"
+	ExchangeTypeTopic  MQExchangeType = "topic"
+	ExchangeTypeDirect MQExchangeType = "direct"
 )
 
 var (
@@ -46,8 +46,6 @@ var (
 		Locale:    defaultLocale,
 	}
 
-	dial       = amqp.Dial
-	dialTLS    = amqp.DialTLS
 	dialConfig = amqp.DialConfig
 )
 
@@ -251,9 +249,9 @@ func (r *rabbitMQConn) tryConnect(secure bool, config *amqp.Config) error {
 
 	if !r.withoutExchange {
 		if r.exchange.Durable {
-			r.Channel.DeclareDurableExchange(r.exchange)
+			_ = r.Channel.DeclareDurableExchange(r.exchange)
 		} else {
-			r.Channel.DeclareExchange(r.exchange)
+			_ = r.Channel.DeclareExchange(r.exchange)
 		}
 		r.ExchangeChannel, err = newRabbitChannel(r.Connection, r.prefetchCount, r.prefetchGlobal, r.confirmPublish)
 	}

broker/rabbitmq/connection_test.go

@@ -6,7 +6,7 @@ import (
 	"testing"
 
 	amqp "github.com/rabbitmq/amqp091-go"
-	"go-micro.dev/v5/logger"
+	"go-micro.dev/v6/logger"
 )
 
 func TestNewRabbitMQConnURL(t *testing.T) {

broker/rabbitmq/context.go

@@ -3,8 +3,8 @@ package rabbitmq
 import (
 	"context"
 
-	"go-micro.dev/v5/broker"
-	"go-micro.dev/v5/server"
+	"go-micro.dev/v6/broker"
+	"go-micro.dev/v6/server"
 )
 
 // setSubscribeOption returns a function to setup a context with given value.

broker/rabbitmq/options.go

@@ -4,9 +4,9 @@ import (
 	"context"
 	"time"
 
-	"go-micro.dev/v5/broker"
-	"go-micro.dev/v5/client"
-	"go-micro.dev/v5/server"
+	"go-micro.dev/v6/broker"
+	"go-micro.dev/v6/client"
+	"go-micro.dev/v6/server"
 )
 
 type durableQueueKey struct{}

broker/rabbitmq/rabbitmq.go

@@ -10,18 +10,16 @@ import (
 	"time"
 
 	amqp "github.com/rabbitmq/amqp091-go"
-	"go-micro.dev/v5/broker"
-	"go-micro.dev/v5/logger"
+	"go-micro.dev/v6/broker"
+	"go-micro.dev/v6/logger"
 )
 
 type rbroker struct {
-	conn           *rabbitMQConn
-	addrs          []string
-	opts           broker.Options
-	prefetchCount  int
-	prefetchGlobal bool
-	mtx            sync.Mutex
-	wg             sync.WaitGroup
+	conn  *rabbitMQConn
+	addrs []string
+	opts  broker.Options
+	mtx   sync.Mutex
+	wg    sync.WaitGroup
 }
 
 type subscriber struct {
@@ -304,9 +302,9 @@ func (r *rbroker) Subscribe(topic string, handler broker.Handler, opts ...broker
 		p := &publication{d: msg, m: m, t: msg.RoutingKey}
 		p.err = handler(p)
 		if p.err == nil && ackSuccess && !opt.AutoAck {
-			msg.Ack(false)
+			_ = msg.Ack(false)
 		} else if p.err != nil && !opt.AutoAck {
-			msg.Nack(false, requeueOnError)
+			_ = msg.Nack(false, requeueOnError)
 		}
 	}
 

broker/rabbitmq/rabbitmq_test.go

@@ -7,12 +7,12 @@ import (
 	"testing"
 	"time"
 
-	"go-micro.dev/v5/logger"
+	"go-micro.dev/v6/logger"
 
-	micro "go-micro.dev/v5"
-	broker "go-micro.dev/v5/broker"
-	rabbitmq "go-micro.dev/v5/broker/rabbitmq"
-	server "go-micro.dev/v5/server"
+	micro "go-micro.dev/v6"
+	broker "go-micro.dev/v6/broker"
+	rabbitmq "go-micro.dev/v6/broker/rabbitmq"
+	server "go-micro.dev/v6/server"
 )
 
 type Example struct{}
@@ -50,8 +50,7 @@ func TestDurable(t *testing.T) {
 
 	s := server.NewServer(server.Broker(b))
 
-	service := micro.NewService(
-		micro.Server(s),
+	service := micro.NewService("test", micro.Server(s),
 		micro.Broker(b),
 	)
 	h := &Example{}
@@ -82,8 +81,7 @@ func TestWithoutExchange(t *testing.T) {
 
 	s := server.NewServer(server.Broker(b))
 
-	service := micro.NewService(
-		micro.Server(s),
+	service := micro.NewService("test", micro.Server(s),
 		micro.Broker(b),
 	)
 	brkrSub := broker.NewSubscribeOptions(
@@ -119,7 +117,7 @@ func TestWithoutExchange(t *testing.T) {
 			rabbitmq.DeliveryMode(2),
 			rabbitmq.ContentType("application/json"))
 		if err != nil {
-			t.Fatal(err)
+			t.Errorf("%v", err)
 		}
 	}()
 
@@ -140,8 +138,7 @@ func TestFanoutExchange(t *testing.T) {
 
 	s := server.NewServer(server.Broker(b))
 
-	service := micro.NewService(
-		micro.Server(s),
+	service := micro.NewService("test", micro.Server(s),
 		micro.Broker(b),
 	)
 	brkrSub := broker.NewSubscribeOptions(
@@ -177,7 +174,7 @@ func TestFanoutExchange(t *testing.T) {
 			rabbitmq.DeliveryMode(2),
 			rabbitmq.ContentType("application/json"))
 		if err != nil {
-			t.Fatal(err)
+			t.Errorf("%v", err)
 		}
 	}()
 
@@ -198,8 +195,7 @@ func TestDirectExchange(t *testing.T) {
 
 	s := server.NewServer(server.Broker(b))
 
-	service := micro.NewService(
-		micro.Server(s),
+	service := micro.NewService("test", micro.Server(s),
 		micro.Broker(b),
 	)
 	brkrSub := broker.NewSubscribeOptions(
@@ -235,7 +231,7 @@ func TestDirectExchange(t *testing.T) {
 			rabbitmq.DeliveryMode(2),
 			rabbitmq.ContentType("application/json"))
 		if err != nil {
-			t.Fatal(err)
+			t.Errorf("%v", err)
 		}
 	}()
 
@@ -256,8 +252,7 @@ func TestTopicExchange(t *testing.T) {
 
 	s := server.NewServer(server.Broker(b))
 
-	service := micro.NewService(
-		micro.Server(s),
+	service := micro.NewService("test", micro.Server(s),
 		micro.Broker(b),
 	)
 	brkrSub := broker.NewSubscribeOptions(
@@ -293,7 +288,7 @@ func TestTopicExchange(t *testing.T) {
 			rabbitmq.DeliveryMode(2),
 			rabbitmq.ContentType("application/json"))
 		if err != nil {
-			t.Fatal(err)
+			t.Errorf("%v", err)
 		}
 	}()
 

cache/memory.go

@@ -14,8 +14,8 @@ type memCache struct {
 }
 
 func (c *memCache) Get(ctx context.Context, key string) (interface{}, time.Time, error) {
-	c.RWMutex.RLock()
-	defer c.RWMutex.RUnlock()
+	c.RLock()
+	defer c.RUnlock()
 
 	item, found := c.items[key]
 	if !found {
@@ -37,8 +37,8 @@ func (c *memCache) Put(ctx context.Context, key string, val interface{}, d time.
 		e = time.Now().Add(d).UnixNano()
 	}
 
-	c.RWMutex.Lock()
-	defer c.RWMutex.Unlock()
+	c.Lock()
+	defer c.Unlock()
 
 	c.items[key] = Item{
 		Value:      val,
@@ -49,8 +49,8 @@ func (c *memCache) Put(ctx context.Context, key string, val interface{}, d time.
 }
 
 func (c *memCache) Delete(ctx context.Context, key string) error {
-	c.RWMutex.Lock()
-	defer c.RWMutex.Unlock()
+	c.Lock()
+	defer c.Unlock()
 
 	_, found := c.items[key]
 	if !found {
@@ -61,6 +61,6 @@ func (c *memCache) Delete(ctx context.Context, key string) error {
 	return nil
 }
 
-func (m *memCache) String() string {
+func (c *memCache) String() string {
 	return "memory"
 }

cache/options.go

@@ -4,7 +4,7 @@ import (
 	"context"
 	"time"
 
-	"go-micro.dev/v5/logger"
+	"go-micro.dev/v6/logger"
 )
 
 // Options represents the options for the cache.

cache/redis/options.go

@@ -4,7 +4,7 @@ import (
 	"context"
 
 	rclient "github.com/go-redis/redis/v8"
-	"go-micro.dev/v5/cache"
+	"go-micro.dev/v6/cache"
 )
 
 type redisOptionsContextKey struct{}

cache/redis/options_test.go

@@ -6,7 +6,7 @@ import (
 	"testing"
 
 	rclient "github.com/go-redis/redis/v8"
-	"go-micro.dev/v5/cache"
+	"go-micro.dev/v6/cache"
 )
 
 func Test_newUniversalClient(t *testing.T) {

cache/redis/redis.go

@@ -5,7 +5,7 @@ import (
 	"time"
 
 	rclient "github.com/go-redis/redis/v8"
-	"go-micro.dev/v5/cache"
+	"go-micro.dev/v6/cache"
 )
 
 // NewRedisCache returns a new redis cache.
@@ -52,6 +52,6 @@ func (c *redisCache) Delete(ctx context.Context, key string) error {
 	return c.client.Del(ctx, key).Err()
 }
 
-func (m *redisCache) String() string {
+func (c *redisCache) String() string {
 	return "redis"
 }

cache/redis/redis_test.go

@@ -6,7 +6,7 @@ import (
 	"testing"
 	"time"
 
-	"go-micro.dev/v5/cache"
+	"go-micro.dev/v6/cache"
 )
 
 var (

client/backoff.go

@@ -4,7 +4,7 @@ import (
 	"context"
 	"time"
 
-	"go-micro.dev/v5/util/backoff"
+	"go-micro.dev/v6/internal/util/backoff"
 )
 
 type BackoffFunc func(ctx context.Context, req Request, attempts int) (time.Duration, error)

client/cache.go

@@ -9,8 +9,8 @@ import (
 
 	cache "github.com/patrickmn/go-cache"
 
-	"go-micro.dev/v5/metadata"
-	"go-micro.dev/v5/transport/headers"
+	"go-micro.dev/v6/metadata"
+	"go-micro.dev/v6/transport/headers"
 )
 
 // NewCache returns an initialized cache.

client/cache_test.go

@@ -5,8 +5,8 @@ import (
 	"testing"
 	"time"
 
-	"go-micro.dev/v5/metadata"
-	"go-micro.dev/v5/transport/headers"
+	"go-micro.dev/v6/metadata"
+	"go-micro.dev/v6/transport/headers"
 )
 
 func TestCache(t *testing.T) {

client/client.go

@@ -4,7 +4,7 @@ package client
 import (
 	"context"
 
-	"go-micro.dev/v5/codec"
+	"go-micro.dev/v6/codec"
 )
 
 var (

client/common_test.go

@@ -1,7 +1,7 @@
 package client
 
 import (
-	"go-micro.dev/v5/registry"
+	"go-micro.dev/v6/registry"
 )
 
 var (

client/grpc/codec.go

@@ -6,8 +6,8 @@ import (
 	"fmt"
 	"strings"
 
-	"go-micro.dev/v5/codec"
-	"go-micro.dev/v5/codec/bytes"
+	"go-micro.dev/v6/codec"
+	"go-micro.dev/v6/codec/bytes"
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/encoding"
 	"google.golang.org/protobuf/encoding/protojson"
@@ -42,7 +42,7 @@ func UseNumber() {
 }
 
 func (w wrapCodec) String() string {
-	return w.Codec.Name()
+	return w.Name()
 }
 
 func (w wrapCodec) Marshal(v interface{}) ([]byte, error) {

client/grpc/error.go

@@ -3,7 +3,7 @@ package grpc
 import (
 	"net/http"
 
-	"go-micro.dev/v5/errors"
+	"go-micro.dev/v6/errors"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
 )

client/grpc/grpc.go

@@ -11,15 +11,15 @@ import (
 	"sync/atomic"
 	"time"
 
-	"go-micro.dev/v5/broker"
-	"go-micro.dev/v5/client"
-	"go-micro.dev/v5/cmd"
-	raw "go-micro.dev/v5/codec/bytes"
-	"go-micro.dev/v5/errors"
-	"go-micro.dev/v5/metadata"
-	"go-micro.dev/v5/registry"
-	"go-micro.dev/v5/selector"
-	pnet "go-micro.dev/v5/util/net"
+	"go-micro.dev/v6/broker"
+	"go-micro.dev/v6/client"
+	"go-micro.dev/v6/cmd"
+	raw "go-micro.dev/v6/codec/bytes"
+	"go-micro.dev/v6/errors"
+	pnet "go-micro.dev/v6/internal/util/net"
+	"go-micro.dev/v6/metadata"
+	"go-micro.dev/v6/registry"
+	"go-micro.dev/v6/selector"
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/credentials"
 	"google.golang.org/grpc/encoding"

client/grpc/grpc_pool.go

@@ -202,7 +202,6 @@ func removeConn(conn *poolConn) {
 	conn.next = nil
 	conn.in = false
 	conn.sp.count--
-	return
 }
 
 func addConnAfter(conn *poolConn, after *poolConn) {
@@ -214,5 +213,4 @@ func addConnAfter(conn *poolConn, after *poolConn) {
 	after.next = conn
 	conn.in = true
 	conn.sp.count++
-	return
 }

client/grpc/grpc_test.go

@@ -5,10 +5,10 @@ import (
 	"net"
 	"testing"
 
-	"go-micro.dev/v5/client"
-	"go-micro.dev/v5/errors"
-	"go-micro.dev/v5/registry"
-	"go-micro.dev/v5/selector"
+	"go-micro.dev/v6/client"
+	"go-micro.dev/v6/errors"
+	"go-micro.dev/v6/registry"
+	"go-micro.dev/v6/selector"
 	pgrpc "google.golang.org/grpc"
 	pb "google.golang.org/grpc/examples/helloworld/helloworld"
 )

client/grpc/message.go

@@ -1,7 +1,7 @@
 package grpc
 
 import (
-	"go-micro.dev/v5/client"
+	"go-micro.dev/v6/client"
 )
 
 type grpcEvent struct {