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 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:

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:

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:

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)
    }
}

SDK

LLM Gateway

Agents

Workflows

Overview

Creating a Handoff

NewHandoff Parameters

Using Handoffs with a Router Agent

Complete Example

​Overview

​Creating a Handoff

​NewHandoff Parameters

​Using Handoffs with a Router Agent

​Complete Example

Overview

Creating a Handoff

NewHandoff Parameters

Using Handoffs with a Router Agent

Complete Example