tools

type AsyncToolHandler ¶

type AsyncToolHandler func(args map[string]any) PendingResult

AsyncToolHandler is a function that may require approval before execution. Return a non-empty PendingResult to indicate approval is needed. Return an empty PendingResult{} to proceed immediately.

type HTTPExecutor ¶

type HTTPExecutor struct {
	// contains filtered or unexported fields
}

HTTPExecutor executes tools that make HTTP calls based on pack configuration. It reads the HTTPConfig from the tool descriptor and makes the appropriate HTTP request.

func NewHTTPExecutor() *HTTPExecutor

func NewHTTPExecutorWithClient(client *http.Client) *HTTPExecutor

func (e *HTTPExecutor) Execute(
	descriptor *tools.ToolDescriptor,
	args json.RawMessage,
) (json.RawMessage, error)

func (e *HTTPExecutor) ExecuteWithContext(
	ctx context.Context,
	descriptor *tools.ToolDescriptor,
	args json.RawMessage,
) (json.RawMessage, error)

func (e *HTTPExecutor) Name() string

type HTTPToolConfig ¶

type HTTPToolConfig struct {
	// contains filtered or unexported fields
}

HTTPToolConfig provides a builder pattern for configuring HTTP tool handlers. This is used with OnToolHTTP to register HTTP-based tools programmatically.

func NewHTTPToolConfig(url string, opts ...HTTPToolOption) *HTTPToolConfig

func (c *HTTPToolConfig) Handler() func(args map[string]any) (any, error)

func (c *HTTPToolConfig) ToDescriptorConfig() *tools.HTTPConfig

type HTTPToolOption ¶

type HTTPToolOption func(*HTTPToolConfig)

HTTPToolOption configures an HTTPToolConfig.

func WithHeader(key, value string) HTTPToolOption

func WithHeaderFromEnv(headerEnv string) HTTPToolOption

func WithMethod(method string) HTTPToolOption

func WithPostProcess(fn func(resp []byte) ([]byte, error)) HTTPToolOption

func WithPreRequest(fn func(req *http.Request) error) HTTPToolOption

func WithRedact(fields ...string) HTTPToolOption

func WithTimeout(ms int) HTTPToolOption

func WithTransform(transform func(args map[string]any) (map[string]any, error)) HTTPToolOption

type HandlerAdapter ¶

type HandlerAdapter struct {
	// contains filtered or unexported fields
}

HandlerAdapter adapts an SDK handler to the runtime's tools.Executor interface.

func NewHandlerAdapter(name string, handler func(args map[string]any) (any, error)) *HandlerAdapter

func (a *HandlerAdapter) Execute(descriptor *tools.ToolDescriptor, args json.RawMessage) (json.RawMessage, error)

func (a *HandlerAdapter) Name() string

type PendingResult ¶

type PendingResult struct {
	// Reason is a machine-readable code for why approval is needed.
	// Examples: "high_value", "sensitive_action", "rate_limited"
	Reason string

	// Message is a human-readable explanation for the approval requirement.
	// This should be suitable for display to an approver.
	Message string
}

PendingResult is returned by async tool handlers to indicate that the tool execution requires external approval.

Example:

conv.OnToolAsync("process_refund", func(args map[string]any) PendingResult {
    amount := args["amount"].(float64)
    if amount > 1000 {
        return PendingResult{
            Reason:  "high_value_refund",
            Message: fmt.Sprintf("Refund of $%.2f requires approval", amount),
        }
    }
    // Return empty to proceed immediately
    return PendingResult{}
})

func (p PendingResult) IsPending() bool

type PendingStore ¶

type PendingStore struct {
	// contains filtered or unexported fields
}

PendingStore manages pending tool calls for a conversation.

func NewPendingStore() *PendingStore

func (s *PendingStore) Add(call *PendingToolCall)

func (s *PendingStore) Clear()

func (s *PendingStore) Get(id string) (*PendingToolCall, bool)

func (s *PendingStore) Len() int

func (s *PendingStore) List() []*PendingToolCall

func (s *PendingStore) Reject(id, reason string) (*ToolResolution, error)

func (s *PendingStore) Remove(id string)

func (s *PendingStore) Resolve(id string) (*ToolResolution, error)

type PendingToolCall ¶

type PendingToolCall struct {
	// Unique identifier for this pending call
	ID string `json:"id"`

	// Tool name
	Name string `json:"name"`

	// Arguments passed to the tool
	Arguments map[string]any `json:"arguments"`

	// Reason the tool requires approval (from PendingResult)
	Reason string `json:"reason"`

	// Human-readable message (from PendingResult)
	Message string `json:"message"`
	// contains filtered or unexported fields
}

PendingToolCall represents a tool call awaiting approval.

func (p *PendingToolCall) SetHandler(h func(args map[string]any) (any, error))

type ResolvedStore ¶ added in v1.1.9

type ResolvedStore struct {
	// contains filtered or unexported fields
}

ResolvedStore tracks tool call resolutions that haven't been processed by Continue(). This allows the Continue() method to send proper tool result messages to the LLM.

func NewResolvedStore() *ResolvedStore

func (s *ResolvedStore) Add(resolution *ToolResolution)

func (s *ResolvedStore) Len() int

func (s *ResolvedStore) PopAll() []*ToolResolution

type ToolHandler ¶

type ToolHandler = func(args map[string]any) (any, error)

ToolHandler is a function type for tool handlers. This mirrors the definition in the main sdk package.

type ToolRegistrar ¶

type ToolRegistrar interface {
	OnTool(name string, handler ToolHandler)
}

ToolRegistrar is the interface for registering tool handlers. This is implemented by [sdk.Conversation].

type ToolResolution ¶

type ToolResolution struct {
	// The resolved tool call ID
	ID string

	// Result if approved and executed
	Result any

	// ResultJSON is the JSON-encoded result
	ResultJSON json.RawMessage

	// Error if execution failed
	Error error

	// Rejected is true if the tool was rejected
	Rejected bool

	// RejectionReason explains why the tool was rejected
	RejectionReason string
}

ToolResolution represents the result of resolving a pending tool.

type TypedHandler ¶

type TypedHandler[T any] func(args T) (any, error)

TypedHandler is a function that executes a tool call with typed arguments. T must be a struct type with fields tagged with `map:"fieldname"`.