> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
last_verified: 2026-10-09
title: Agents
description: Create Go agents with NewAgent, run them, register them, and hand off between agents
category: Go SDK
hideRightSidebar: true
---

An agent is a model running in a loop with instructions and tools: it calls tools until it can answer. For a guided introduction, see [Agents](/docs/build/agents.md).

## `agnt5.NewAgent(name, opts...)`

```go
model := agnt5.NewOpenAIModel(agnt5.OpenAIConfig{
	APIKey: os.Getenv("OPENAI_API_KEY"),
	Model:  "gpt-6-luna",
})

weatherAgent, err := agnt5.NewAgent("weather_agent",
	agnt5.WithAgentModel(model),
	agnt5.WithAgentInstructions("Answer weather questions. Call get_weather for the city."),
	agnt5.WithAgentTools(getWeather),
	agnt5.WithAgentMaxTurns(5),
)
if err != nil {
	log.Fatal(err)
}
```

| Option | Description |
|---|---|
| `WithAgentModel(model)` | The model client. See [LM](/sdk/go/lm.md). |
| `WithAgentInstructions(text)` | The system instructions. |
| `WithAgentTools(tools...)` | [Tools](/sdk/go/tools.md) the agent can call. |
| `WithAgentHandoffs(handoffs...)` | Agents to hand the conversation to. See [Handoffs](#handoffs). |
| `WithAgentMaxTurns(n)` | Most model calls in one run. |
| `WithAgentReasoningEffort(effort)` | Reasoning effort for models that reason, for example `"low"`. |
| `WithAgentPromptCache(cache)` | [Prompt caching](/docs/build/prompt-caching.md), for example `agnt5.PromptCacheWithTTL("1h")`. |
| `WithAgentSandbox(sandbox)` | A [sandbox](/docs/build/sandboxes.md) for file and code tools. |
| `WithAgentSkills(skills...)`, `WithAgentSkillsFromDir(dir, names...)` | [Skills](/docs/build/skills.md) the agent can load. |
| `WithAgentGuidance(sources...)` | `AGENTS.md` guidance. |

## Run an agent

### `agent.Run(ctx, input)`

```go
result, err := weatherAgent.Run(ctx, agnt5.AgentInput{Message: "What is the weather in Paris?"})
if err != nil {
	return "", err
}
return result.Response, nil
```

Pass the handler's `ctx` so model and tool calls are traced inside the run. `AgentInput` takes a `Message`, or prior `Messages` for a conversation.

| `AgentResult` field | Description |
|---|---|
| `Response` | The agent's final answer. |
| `AgentName` | The agent that produced it. |
| `ToolCalls` | How many tool calls the run made. |
| `ToolCallDetails` | Each tool call. |
| `Messages` | The full conversation, including tool calls. |
| `HandoffTo` | The agent that took over, or empty. |

### Register an agent

`agnt5.RegisterAgent(worker, agent)` makes the agent runnable on its own:

```bash
agnt5 run weather_agent --type agent --input '{"message": "Weather in Rome?"}'
```

## Handoffs

`agnt5.NewHandoff(agent, opts...)` lets an agent pass the conversation to another agent. The model sees a tool named `transfer_to_<agent>`, and the run's `HandoffTo` names the agent that answered:

```go
billing, err := agnt5.NewAgent("billing",
	agnt5.WithAgentModel(model),
	agnt5.WithAgentInstructions("You handle billing questions."),
)
if err != nil {
	log.Fatal(err)
}

toBilling, err := agnt5.NewHandoff(billing, agnt5.WithHandoffDescription("Billing questions"))
if err != nil {
	log.Fatal(err)
}

triage, err := agnt5.NewAgent("triage",
	agnt5.WithAgentModel(model),
	agnt5.WithAgentInstructions("Route billing questions to the billing agent."),
	agnt5.WithAgentHandoffs(toBilling),
)
```

To get another agent's answer back as a tool result instead, wrap it in a tool: see [Agents as tools](/docs/build/agents.md).

## Next steps

* [Tools](/sdk/go/tools.md): define the tools an agent calls.
* [LM](/sdk/go/lm.md): model clients and direct model calls.
* [Agents guide](/docs/build/agents.md): handoffs and agents as tools in practice.