Agents

An agent combines a model, instructions, and tools. Service endpoints become its tools, so you can use the same operations from code and conversation.

New → Run → Chat

Install the CLI from master until this feature is released:

go install go-micro.dev/v6/cmd/micro@master

The released v6.15.1 CLI supports the service-only getting-started path, but does not include this combined scaffold. Check the binary you are about to use with micro --version.

Create and run a service with an agent:

micro new weather --agent
cd weather
export OPENAI_API_KEY=your-key # or another supported provider key
micro run

In another terminal:

micro call weather Weather.Call '{"name":"Alice"}'
micro chat weather

Ask it to greet Alice. The generated Weather.Call handler returns “Hello Alice”. The name does not generate weather functionality: add your own methods in handler/ to implement that. The agent uses those methods as tools.

The service hosts RPC and chat on the same server, with one discovery entry and one lifecycle. Configure the provider on the service; the chat client needs no model credentials. micro run builds and watches the service; go run . also works. Use micro gateway separately when you need HTTP or MCP.

Add an agent to a service

Register your business handlers, then attach an agent before running the service:

if err := service.Handle(handler.New()); err != nil {
    log.Fatal(err)
}
if err := service.Handle(micro.NewAgent("weather")); err != nil {
    log.Fatal(err)
}
if err := service.Run(); err != nil {
    log.Fatal(err)
}

The service owns the agent’s name, client, registry, broker, storage, and shutdown. By default, the attached agent can use only this service’s business endpoints. Use micro.AgentServices("weather", "notes") to select other services as well. Agent chat, session, task, and schedule endpoints are excluded from model tools.

micro new --agent uses the default Go handler template. It does not need a model key to scaffold the project. --prompt is a separate, optional code-generation path; it is not part of this workflow.

Standalone agent

An agent can also run separately and use existing services. Keep the notes service running. In your project, create cmd/assistant/main.go:

package main

import (
    "log"
    "os"

    micro "go-micro.dev/v6"
)

func main() {
    agent := micro.NewAgent("assistant",
        micro.AgentProvider("openai"),
        micro.AgentAPIKey(os.Getenv("OPENAI_API_KEY")),
        micro.AgentServices("notes"),
        micro.AgentPrompt("Use the notes service to answer questions about notes."),
    )
    if err := agent.Run(); err != nil {
        log.Fatal(err)
    }
}

Start it in a second terminal with your provider key:

export OPENAI_API_KEY=your-key
go run ./cmd/assistant

Use it

Wait for the agent to register, then in a third terminal:

micro chat assistant

This connects explicitly to assistant. Ask:

What notes do I have?

The agent can call Notes.List and answer using its result. Check the tool activity to see that the service was called. This uses your model provider and incurs its normal API charges.

Use /agents to list available agents and /agent NAME to switch. /agent micro returns to the built-in development agent. Each destination keeps its own conversation. Plain micro chat always starts the built-in agent.

Your Go code controls the provider, instructions, and allowed services. Change those options to build your own agent. For programmatic calls, the agent exposes Ask(ctx, message); see the agent API.

Configure the provider and its key in the agent process. The service and tools stay the same when you change models; chat connects to the running agent.

Discovery

Agents use mDNS by default. For another registry, give the agent and its client the same registry. For NATS, import agent, client, registry, and registry/nats from go-micro.dev/v6, then add these options:

reg := nats.NewNatsRegistry(registry.Addrs("127.0.0.1:4222"))
a := micro.NewAgent("assistant",
    agent.WithRegistry(reg),
    agent.WithClient(client.NewClient(client.Registry(reg))),
    micro.AgentServices("notes"),
    // Your model and instructions, as above.
)

The CLI’s MICRO_REGISTRY settings configure CLI processes. Library code selects its components through Go options.

Execution

Ask runs work in the caller’s context. StartTask runs work in the agent host and returns a task ID; GetTask reads its result and StopTask cancels it. Scheduled work uses that same task path. Keep the host running with Run and shut it down with Stop.

For recovery, configure agent.WithCheckpoint(agent.StoreCheckpoint(st, "assistant")), where st is your persistent store. agent.Pending lists unfinished runs and agent.Resume resumes a chosen run. Recovery is explicit: a tool interrupted by a crash may already have performed its action.

These are agent capabilities; no workflow definition is required. sequence of operations.

Call an agent from Go

Use the same registry configuration as the running agent. The host owns its model credentials and tools; the client only needs RPC access.

remote := agent.NewClient("assistant", client.DefaultClient)
ctx := agent.WithSession(context.Background(), "my-conversation")
response, err := remote.Ask(ctx, "What notes do I have?")
if err != nil {
    return err
}
fmt.Println(response.Reply)

The packages are go-micro.dev/v6/agent and go-micro.dev/v6/client. Reuse the session ID to continue a conversation. Use a different ID for each conversation; the host must authenticate and authorize access separately.

For live text, tool activity and approvals, use remote.StreamAsk(ctx, message). It returns the same agent.StreamEvent values used by local agents:

stream, err := remote.StreamAsk(ctx, "Read my notes")
if err != nil {
    return err
}
defer stream.Close()
for {
    event, err := stream.Recv()
    if errors.Is(err, io.EOF) {
        break
    }
    if err != nil {
        return err
    }
    switch event.Type {
    case agent.StreamEventToken:
        fmt.Print(event.Token)
    case agent.StreamEventApproval:
        // Ask the user here. This example refuses the action.
        if err := stream.Approve(event.ApprovalID, false); err != nil {
            return err
        }
    }
}

Cancelling the context or closing the stream cancels unfinished work. Use stream.Context() when waiting for a user decision so a disconnect also ends the wait. A disconnect before completion returns an error; calls are never retried automatically because actions may already have taken effect. Streaming requires a host with the AgentInteraction endpoint.