Human in the Loop

Human-in-the-loop (HITL) allows you to require human approval before executing sensitive tool calls. When a tool marked as requiring approval is invoked by the agent, the execution pauses and waits for explicit user confirmation before proceeding.

How It Works

Tool invocation: The agent decides to call a tool that requires approval
Execution pauses: The run transitions to an await_approval state
User reviews: The pending tool call is presented to the user for review
User responds: The user approves or rejects the tool call
Execution resumes: The agent continues with the approved tools or handles rejections

Configuring Approval for Custom Tools

To require approval for a custom function tool, embed agents.BaseTool and set RequiresApproval: true:

type DeleteUserTool struct {
    *agents.BaseTool
}

func NewDeleteUserTool() *DeleteUserTool {
    return &DeleteUserTool{
        BaseTool: &agents.BaseTool{
            RequiresApproval: true,  // Requires human approval
            ToolUnion: responses.ToolUnion{
                OfFunction: &responses.FunctionTool{
                    Name:        "delete_user",
                    Description: utils.Ptr("Permanently deletes a user account"),
                    Parameters: map[string]any{
                        "type": "object",
                        "properties": map[string]any{
                            "user_id": map[string]any{
                                "type":        "string",
                                "description": "The ID of the user to delete",
                            },
                        },
                        "required": []string{"user_id"},
                    },
                },
            },
        },
    }
}

func (t *DeleteUserTool) Execute(ctx context.Context, params *agents.ToolCall) (*agents.ToolCallResponse, error) {
    // This only runs after human approval
    args := map[string]interface{}{}
    json.Unmarshal([]byte(params.Arguments), &args)
    
    userID := args["user_id"].(string)
    err := deleteUser(userID)
    
    return &agents.ToolCallResponse{
        FunctionCallOutputMessage: &responses.FunctionCallOutputMessage{
            ID:     params.ID,
            CallID: params.CallID,
            Output: responses.FunctionCallOutputContentUnion{
                OfString: utils.Ptr(fmt.Sprintf("User %s deleted successfully", userID)),
            },
        },
    }, err
}

Configuring Approval for MCP Tools

For MCP tools, use the WithMcpApprovalRequiredTools option when retrieving tools:

mcpClient, err := mcpclient.NewClient(context.Background(), "http://localhost:9001/sse",
		mcpclient.WithTransport("sse"),
		mcpclient.WithHeaders(map[string]string{
			"token": "your-token",
		}),
		mcpclient.WithToolFilter("list_users"),
		mcpclient.WithApprovalRequiredTools("list_users"),
	)
if err != nil {
    log.Fatal(err)
}

agent := hastekit.NewAgent(&hastekit.AgentConfig{
    Name:        "Assistant",
    Instruction: hastekit.NewPrompt("You are a helpful assistant."),
    LLM:         model,
    McpServers:  []agents.MCPToolset{mcpClient},
})

Handling Approval in Your Application

When a tool requires approval, the agent execution pauses and returns with a paused status. The pending tool calls are available in the run state.

Agent Output

Execute() (via the handle’s Result()/Wait()) returns an *agents.AgentOutput. When approval is needed, its Status is RunStatusPaused and the paused run exposes one Interrupt per pending tool call in Interrupts:

type AgentOutput struct {
    RunID      string                        `json:"run_id"`
    Status     agentstate.RunStatus          `json:"status"`               // RunStatusPaused when approval is required
    Output     []responses.InputMessageUnion `json:"output"`
    Interrupts []responses.Interrupt         `json:"interrupts,omitempty"` // One per tool call awaiting approval
}

Each Interrupt carries the intercepted call and the kind of gate:

type Interrupt struct {
    FunctionCallMessage responses.FunctionCallMessage `json:"function_call_message"` // .CallID identifies the call
    Mode                responses.InterruptMode       `json:"mode"`                  // "approval" for approve/reject gates
    IsNested            bool                          `json:"is_nested,omitempty"`
}

Approval-required tools inside sub-agents (see Agent as a tool) bubble up to the parent’s Interrupts with IsNested: true, so the parent run pauses and surfaces them just like its own tools.

Resuming Execution

To resume execution after user review, send a FunctionCallInterruptResolutionMessage on the same thread, resolving each call by ID with InterruptActionApprove or InterruptActionReject. Execute() returns an *AgentHandle; the simplest way to wait for the resumed run is handle.Result():

// User approved the tool call
approvalResponse := responses.InputMessageUnion{
    OfFunctionCallInterruptResolution: &responses.FunctionCallInterruptResolutionMessage{
        ID: uuid.NewString(),
        Resolutions: []responses.InterruptResolution{
            {
                CallID: result.Interrupts[0].FunctionCallMessage.CallID,
                Action: responses.InterruptActionApprove,
            },
        },
    },
}

handle, err := agent.Execute(ctx, &agents.AgentInput{
    Message: history.Message{
        Messages: []responses.InputMessageUnion{approvalResponse},
    },
})
if err != nil {
    log.Fatal(err)
}
result, err := handle.Result()

Handling Rejections

To reject a call, resolve it with InterruptActionReject. You can approve some calls and reject others in the same Resolutions slice:

// User rejected the tool call
approvalResponse := responses.InputMessageUnion{
    OfFunctionCallInterruptResolution: &responses.FunctionCallInterruptResolutionMessage{
        ID: uuid.NewString(),
        Resolutions: []responses.InterruptResolution{
            {
                CallID: result.Interrupts[0].FunctionCallMessage.CallID,
                Action: responses.InterruptActionReject,
            },
        },
    },
}

The agent will receive the rejection as tool output: "Request to call this tool has been declined" and can adjust its response accordingly.

Complete Example

Here’s a complete example with a mix of immediate and approval-required tools:

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"os"

	"github.com/bytedance/sonic"
	"github.com/google/uuid"
	"github.com/hastekit/hastekit-sdk-go/pkg/agents"
	"github.com/hastekit/hastekit-sdk-go/pkg/agents/agentstate"
	"github.com/hastekit/hastekit-sdk-go/pkg/agents/history"
	"github.com/hastekit/hastekit-sdk-go/pkg/gateway/llm/responses"
	hastekit "github.com/hastekit/hastekit-sdk-go"
	"github.com/hastekit/hastekit-sdk-go/pkg/utils"
)

// GetUserTool - runs immediately (no approval needed)
type GetUserTool struct {
	*agents.BaseTool
}

func NewGetUserTool() *GetUserTool {
	return &GetUserTool{
		BaseTool: &agents.BaseTool{
			RequiresApproval: false,
			ToolUnion: responses.ToolUnion{
				OfFunction: &responses.FunctionTool{
					Name:        "get_user",
					Description: utils.Ptr("Gets user information"),
					Parameters: map[string]any{
						"type": "object",
						"properties": map[string]any{
							"user_id": map[string]any{"type": "string"},
						},
						"required": []string{"user_id"},
					},
				},
			},
		},
	}
}

func (t *GetUserTool) Execute(ctx context.Context, params *agents.ToolCall) (*agents.ToolCallResponse, error) {
	return &agents.ToolCallResponse{
		FunctionCallOutputMessage: &responses.FunctionCallOutputMessage{
			ID:     params.ID,
			CallID: params.CallID,
			Output: responses.FunctionCallOutputContentUnion{
				OfString: utils.Ptr(`{"name": "John Doe", "email": "john@example.com"}`),
			},
		},
	}, nil
}

// DeleteUserTool - requires approval
type DeleteUserTool struct {
	*agents.BaseTool
}

func NewDeleteUserTool() *DeleteUserTool {
	return &DeleteUserTool{
		BaseTool: &agents.BaseTool{
			RequiresApproval: true, // Human approval required
			ToolUnion: responses.ToolUnion{
				OfFunction: &responses.FunctionTool{
					Name:        "delete_user",
					Description: utils.Ptr("Permanently deletes a user account"),
					Parameters: map[string]any{
						"type": "object",
						"properties": map[string]any{
							"user_id": map[string]any{"type": "string"},
						},
						"required": []string{"user_id"},
					},
				},
			},
		},
	}
}

func (t *DeleteUserTool) Execute(ctx context.Context, params *agents.ToolCall) (*agents.ToolCallResponse, error) {
	args := map[string]any{}
	json.Unmarshal([]byte(params.Arguments), &args)

	return &agents.ToolCallResponse{
		FunctionCallOutputMessage: &responses.FunctionCallOutputMessage{
			ID:     params.ID,
			CallID: params.CallID,
			Output: responses.FunctionCallOutputContentUnion{
				OfString: utils.Ptr(fmt.Sprintf("User %s has been deleted", args["user_id"])),
			},
		},
	}, nil
}

func main() {
	ctx := context.Background()

    client := hastekit.NewLLMClient([]hastekit.ProviderConfig{
        {
            ProviderName: hastekit.ProviderOpenAI,
            ApiKeys: []*hastekit.APIKeyConfig{
                {
                    Name:   "Key 1",
                    APIKey: os.Getenv("OPENAI_API_KEY"),
                },
            },
        },
    })

	agent := hastekit.NewAgent(&hastekit.AgentConfig{
		Name:        "User Manager",
		Instruction: hastekit.NewPrompt("You help manage user accounts."),
		LLM:         client.Model("OpenAI/gpt-4o-mini"),
		Tools: []hastekit.Tool{
			NewGetUserTool(),
			NewDeleteUserTool(),
		},
		History: hastekit.NewFileHistory("./conversations"),
	})

	// First execution - agent may request to delete a user
	handle, err := agent.Execute(ctx, &agents.AgentInput{
		Namespace: "default",
		Message: history.Message{
            Messages: []responses.InputMessageUnion{
			    responses.UserMessage("Delete user 123"),
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	result, err := handle.Result()
	if err != nil {
		log.Fatal(err)
	}

	// Check if approval is needed
	if result.Status == agentstate.RunStatusPaused {
		fmt.Println("Approval required for:", result.Interrupts)

		// Simulate user approval
		approvalResponse := responses.InputMessageUnion{
			OfFunctionCallInterruptResolution: &responses.FunctionCallInterruptResolutionMessage{
				ID: uuid.NewString(),
				Resolutions: []responses.InterruptResolution{
					{
						CallID: result.Interrupts[0].FunctionCallMessage.CallID,
						Action: responses.InterruptActionApprove,
					},
				},
			},
		}

		// Resume with approval
		handle, err = agent.Execute(ctx, &agents.AgentInput{
			Namespace:         "default",
			PreviousMessageID: result.RunID,
			Message: history.Message{
				Messages: []responses.InputMessageUnion{approvalResponse},
			},
		})
		if err != nil {
			log.Fatal(err)
		}
		result, err = handle.Result()
		if err != nil {
			log.Fatal(err)
		}
	}

	buf, _ := sonic.Marshal(result.Output)
	fmt.Println("Final result:", string(buf))
}

SDK

LLM Gateway

Agents

Workflows

Human in the Loop

How It Works

Configuring Approval for Custom Tools

Configuring Approval for MCP Tools

Handling Approval in Your Application

Agent Output

Resuming Execution

Handling Rejections

Complete Example

​How It Works

​Configuring Approval for Custom Tools

​Configuring Approval for MCP Tools

​Handling Approval in Your Application

​Agent Output

​Resuming Execution

​Handling Rejections

​Complete Example

How It Works

Configuring Approval for Custom Tools

Configuring Approval for MCP Tools

Handling Approval in Your Application

Agent Output

Resuming Execution

Handling Rejections

Complete Example