Your First Agent

This walkthrough builds the smallest useful Go Micro agent path: one service with typed endpoints, one agent scoped to that service, and one CLI conversation that proves the agent can use the service as a tool. It is the 0→1 version of the services → agents → workflows lifecycle: build capability first, add intelligence on top, then keep a clear path toward flows when the work needs to run on events or schedules.

Runnable reference first

If you want to run the lifecycle before copying code, start with the maintained support-desk example from the repository root:

go run ./examples/support

It uses a deterministic mock model by default, so it needs no provider key, and it exercises the same shape this guide teaches: services become tools, an agent uses them, and a flow can trigger the work. Use this guide when you are ready to build the smaller 0→1 version yourself.

What you'll build

A tiny task assistant:

1. A task service exposes Create and List endpoints.
2. An assistant agent is scoped to the task service.
3. micro run starts both in the local harness.
4. micro chat asks the agent to create and list tasks.

The same service endpoints are normal RPC methods, dashboard/API actions, MCP tools, and agent tools. You do not write a second integration layer for the agent.

Prerequisites

• Go 1.24 or newer.
• The micro CLI installed.
• An LLM provider key for live agent calls. For example:

export ANTHROPIC_API_KEY=sk-ant-...

Plain service calls work without a model key; the key is only needed when the agent reasons over tools.

Run the read-only first-agent preflight before starting the walkthrough. The same CLI boundary is covered by CI with go test ./cmd/micro -run TestFirstAgentWalkthroughCLIBoundaries -count=1, so the documented scaffold → run → chat → inspect path stays visible in the local harness:

micro agent preflight

It checks Go, the micro binary, provider-key setup, and the default local gateway port without contacting a provider.

1. Create a workspace

mkdir first-agent
cd first-agent
go mod init example.com/first-agent
go get go-micro.dev/v6@v6

Add main.go:

package main

import (
	"context"
	"fmt"
	"os"
	"sync"

	micro "go-micro.dev/v6"
)

type CreateRequest struct {
	Title string `json:"title"`
}

type CreateResponse struct {
	ID    string `json:"id"`
	Title string `json:"title"`
}

type ListRequest struct{}

type ListResponse struct {
	Tasks []CreateResponse `json:"tasks"`
}

type TaskService struct {
	mu    sync.Mutex
	next  int
	tasks []CreateResponse
}

// Create adds a task to the list.
// @example {"title":"Write first agent guide"}
func (t *TaskService) Create(ctx context.Context, req *CreateRequest, rsp *CreateResponse) error {
	t.mu.Lock()
	defer t.mu.Unlock()

	t.next++
	*rsp = CreateResponse{ID: fmt.Sprintf("task-%d", t.next), Title: req.Title}
	t.tasks = append(t.tasks, *rsp)
	return nil
}

// List returns all known tasks.
// @example {}
func (t *TaskService) List(ctx context.Context, req *ListRequest, rsp *ListResponse) error {
	t.mu.Lock()
	defer t.mu.Unlock()

	rsp.Tasks = append([]CreateResponse(nil), t.tasks...)
	return nil
}

func main() {
	service := micro.NewService("task")
	service.Handle(new(TaskService))

	agent := micro.NewAgent("assistant",
		micro.AgentServices("task"),
		micro.AgentPrompt("You help manage tasks. Use the task service before answering."),
		micro.AgentProvider("anthropic"),
		micro.AgentAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
	)

	go agent.Run()
	service.Run()
}

Why the comments matter: endpoint comments and @example tags become tool descriptions, so the agent has enough context to choose task.Create and task.List correctly.

2. Run the service and agent

From the same directory:

micro run

The local harness starts the service, gateway, dashboard, MCP tool surface, and agent playground. You can also verify the service directly before involving the agent:

micro call task TaskService.Create '{"title":"Ship the walkthrough"}'
micro call task TaskService.List '{}'

3. Chat with the agent

In another terminal, ask the agent to use the service:

micro chat assistant

Try:

Create a task called "Review the first-agent walkthrough", then show me all tasks.

A healthy run shows the agent calling the task service and then summarizing the result. If the model refuses to call tools, tighten the prompt so it explicitly uses the task service before answering.

4. Know what just happened

• The service registered typed RPC endpoints.
• Go Micro derived tool descriptions from the endpoint names, comments, request fields, and examples.
• The agent registered as another service with an Agent.Chat endpoint.
• micro chat sent your message to the agent.
• The agent selected the scoped task tools, called them over the same runtime, and stored conversation history in memory.

That is the core lifecycle: services provide capability, agents use the capability, and the same runtime can later put the interaction behind a flow.

5. Make it a workflow when the path is event-driven

Once the prompt should run because something happened rather than because a human typed a message, move the handoff into a flow:

flow := micro.NewFlow("task-triage",
	micro.FlowTrigger("tasks.created"),
	micro.FlowPrompt("Review this new task and decide the next action: {{.Data}}"),
	micro.FlowProvider("anthropic"),
	micro.FlowAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
)

Use flows for deterministic triggers and long-running orchestration; keep the agent for judgment, tool use, and handoffs when the path is not known up front.

Troubleshooting

Next steps

• Read the 0→hero reference path for the CI-verified lifecycle contract.
• Run examples/support for the no-secret 0→hero support-desk lifecycle.
• Run examples/agent-plan-delegate to see planning and delegation across agents.
• Read Debugging your agent when a chat turn does not call the tool you expected, loops, refuses a call, loses memory, or fails after a flow handoff.
• Read Agents and Workflows when you are ready to compose agents behind durable flows.