> ## Documentation Index
> Fetch the complete documentation index at: https://hastekit.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Handoff

Agent handoff enables a one agent to delegate tasks to others agents based on the user's request. This pattern is useful for building multi-agent systems where different agents have specific capabilities, and a central agent routes requests to the appropriate specialist.

## Overview

Handoffs allow you to:

* **Route requests**: A router agent analyzes user input and delegates to the right specialist
* **Specialize agents**: Create focused agents for specific tasks (jokes, facts, code, etc.)
* **Share conversation context**: Handoff agents can share conversation history for continuity
* **Build hierarchical systems**: Combine multiple specialists under one entry point

Unlike [Agent as a Tool](/docs/hastekit-sdk/agents/tools/agent-as-a-tool) where the parent agent calls sub-agents as tools and continues processing, handoffs transfer control entirely to the target agent, which then responds directly to the user.

## Creating a Handoff

To create a handoff, use `agents.NewHandoff()` with the target agent:

```go theme={null}
import (
    "github.com/hastekit/hastekit-sdk-go/pkg/agents"
)

// Create a specialized agent
jokeAgent := hastekit.NewAgent(&hastekit.AgentConfig{
    Name:        "JokeAgent",
    Instruction: hastekit.NewPrompt("You are a joke teller"),
    LLM:         model,
    History:     hastekit.NewFileHistory("./conversations"),
})

// Create a handoff to this agent
handoff := agents.NewHandoff(
    jokeAgent.Name,                           // Name (used for routing)
    "Use this agent to generate jokes",       // Description (helps router decide)
    jokeAgent,                                // Target agent
)
```

### NewHandoff Parameters

| Parameter | Type     | Description                                                             |
| :-------- | :------- | :---------------------------------------------------------------------- |
| **name**  | `string` | Name of the handoff (typically matches the agent name)                  |
| **desc**  | `string` | Description that helps the router agent decide when to use this handoff |
| **agent** | `*Agent` | The target agent that will handle the request                           |

## Using Handoffs with a Router Agent

Handoffs are configured on the router agent using the `Handoffs` field in `AgentConfig`:

```go theme={null}
routerAgent := hastekit.NewAgent(&hastekit.AgentConfig{
    Name:        "RouterAgent",
    Instruction: hastekit.NewPrompt("You are a router agent. You must not respond directly. Your role is only to delegate to other agents"),
    LLM:         model,
    Handoffs: []*agents.Handoff{
        agents.NewHandoff(jokeAgent.Name, "Use this agent to generate jokes", jokeAgent),
        agents.NewHandoff(factAgent.Name, "Use this agent to generate facts", factAgent),
    },
    History: hastekit.NewFileHistory("./conversations"),
})
```

The router agent uses the handoff descriptions to determine which agent should handle each request. Write clear, specific descriptions to help the router make accurate routing decisions.

## Complete Example

Here's a complete example demonstrating a router agent that delegates to specialized joke and fact agents:

```go theme={null}
package main

import (
    "log"
    "net/http"
    "os"

    hastekit "github.com/hastekit/hastekit-sdk-go"
    "github.com/hastekit/hastekit-sdk-go/pkg/agents"
)

func main() {
    // Configure an LLM client
    client := hastekit.NewLLMClient([]hastekit.ProviderConfig{
        {
            ProviderName:  hastekit.ProviderOpenAI,
            BaseURL:       "",
            CustomHeaders: nil,
            ApiKeys: []*hastekit.APIKeyConfig{
                {
                    Name:   "Key 1",
                    APIKey: os.Getenv("OPENAI_API_KEY"),
                },
            },
        },
    })

    // Create LLM model
    model := client.Model("OpenAI/gpt-4.1-mini")

    // Create specialized agents
    jokeAgent := hastekit.NewAgent(&hastekit.AgentConfig{
        Name:        "JokeAgent",
        Instruction: hastekit.NewPrompt("You are a joke teller"),
        LLM:         model,
        History:     hastekit.NewFileHistory("./conversations"),
    })

    factAgent := hastekit.NewAgent(&hastekit.AgentConfig{
        Name:        "FactAgent",
        Instruction: hastekit.NewPrompt("You are a fact teller"),
        LLM:         model,
        History:     hastekit.NewFileHistory("./conversations"),
    })

    // Create router agent with handoffs
    _ = hastekit.NewAgent(&hastekit.AgentConfig{
        Name:        "RouterAgent",
        Instruction: hastekit.NewPrompt("You are a router agent. You must not respond directly. Your role is only to delegate to other agents"),
        LLM:         model,
        Handoffs: []*agents.Handoff{
            agents.NewHandoff(jokeAgent.Name, "Use this agent to generate jokes", jokeAgent),
            agents.NewHandoff(factAgent.Name, "Use this agent to generate facts", factAgent),
        },
        History: hastekit.NewFileHistory("./conversations"),
    })

    // Serve the agents
    err := http.ListenAndServe(":8070", hastekit.NewHTTPHandler())
    if err != nil {
        log.Fatal(err)
    }
}
```