agents-go docs

The Quickstart ran the smallest possible agent. This builds a slightly fuller one: an agent with real instructions, a tool the model can call, and a turn driven end to end — still text-only and offline so it runs anywhere.

Define a tool

The agent can look up the weather. The input type becomes the tool's schema.

type WeatherInput struct {
    City string `json:"city" description:"city name" min:"1"`
}
type WeatherOutput struct {
    Summary string `json:"summary"`
}

getWeather, err := tool.New("get_weather",
    func(ctx context.Context, run *tool.RunContext, in *WeatherInput) (*WeatherOutput, error) {
        return &WeatherOutput{Summary: "clear, 21°C"}, nil
    },
    tool.WithDescription("Get the current weather for a city."),
)
if err != nil {
    return err
}

Build the agent

Give it instructions and the tool.

agent, err := agents.NewAgent(agents.AgentOptions{
    Instructions: "You are a concise weather assistant. Use get_weather for live data.",
    Tools:        []tool.Entry{getWeather},
    LLM:          model, // an llm.LLM from a provider plugin
})
if err != nil {
    return err
}

Start a session and run a turn

session.Run generates one reply — including any tool calls — and blocks until it finishes.

session := agents.MustNewAgentSession(agents.AgentSessionOptions{})
if err := session.Start(ctx, agents.StartOptions{Agent: agent}); err != nil {
    return err
}
defer func() { _ = session.Close(context.Background()) }()

result, err := session.Run(ctx, agents.RunOptions{
    UserInput: "What's the weather in Sydney?",
})
if err != nil {
    return err
}
fmt.Println(result.FinalOutput())

The model calls get_weather, the runtime runs your handler, folds the result back in, and produces the final reply — which FinalOutput() returns.

What just happened

Instructions

Shaped the persona and told the model when to use the tool.

Tool call

The model chose to call get_weather; the runtime decoded args, ran your Go handler, and returned the result.

Turn

session.Run drove one text turn (no audio) straight through generation to a final answer.

Make it a voice agent — Build a voice agent.
Understand the loop — How a turn flows.
Add more tools — Define tools.

Your first agent