Documentation
¶
Overview ¶
Package middleware provides reusable hooks for common cross-cutting concerns like logging, metrics collection, and panic recovery.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Logging ¶
Logging returns a pair of hooks that log tool execution start and completion using the provided slog.Logger. If logger is nil, slog.Default() is used.
agent := agentflow.NewAgent(provider,
agentflow.WithHook(middleware.Logging(logger)...),
)
func MaxTurnsGuard ¶
MaxTurnsGuard returns an OnTurnEnd hook that logs a warning when the agent approaches the turn limit. Useful for observability.
func Recovery ¶
Recovery returns a PreToolUse hook that wraps tool execution with panic recovery. If a tool panics, the panic is caught, logged, and converted to an error result instead of crashing the agent loop.
Note: The Agent already includes basic panic recovery in callToolWithRecovery. This middleware adds structured logging of the stack trace.
Types ¶
type CircuitBreaker ¶
type CircuitBreaker struct {
// contains filtered or unexported fields
}
CircuitBreaker blocks tool execution after consecutive failures exceed a threshold. After a reset duration, the circuit enters half-open state and allows a single probe request. If it succeeds, the circuit closes; if it fails, it re-opens.
cb := middleware.NewCircuitBreaker(3, 30*time.Second)
agent := agentflow.NewAgent(provider,
agentflow.WithHook(cb.Hooks()[0]),
agentflow.WithHook(cb.Hooks()[1]),
)
func NewCircuitBreaker ¶
func NewCircuitBreaker(threshold int, resetDuration time.Duration) *CircuitBreaker
NewCircuitBreaker creates a circuit breaker that opens after threshold consecutive failures and attempts recovery after resetDuration.
func (*CircuitBreaker) Hooks ¶
func (cb *CircuitBreaker) Hooks() []agentflow.Hook
Hooks returns PreToolUse (to block) and PostToolUse (to track) hooks.
func (*CircuitBreaker) Reset ¶
func (cb *CircuitBreaker) Reset()
Reset clears the circuit breaker state for all tools.
func (*CircuitBreaker) State ¶
func (cb *CircuitBreaker) State(toolName string) CircuitState
State returns the current circuit state for a tool. Returns CircuitClosed if the tool has no circuit breaker state.
type CircuitState ¶
type CircuitState int
CircuitState represents the current state of a circuit breaker.
const ( // CircuitClosed allows all requests through (normal operation). CircuitClosed CircuitState = iota // CircuitOpen blocks all requests (too many failures). CircuitOpen // CircuitHalfOpen allows a single probe request to test recovery. CircuitHalfOpen )
type Metrics ¶
type Metrics struct {
// contains filtered or unexported fields
}
Metrics collects execution statistics from the agent loop. It provides a thread-safe, in-memory view of tool call counts, durations, and error rates.
m := middleware.NewMetrics()
agent := agentflow.NewAgent(provider,
agentflow.WithHook(m.Hooks()...),
)
// After agent run:
fmt.Println(m.Snapshot())
func (*Metrics) Snapshot ¶
func (m *Metrics) Snapshot() MetricsSnapshot
Snapshot returns a point-in-time copy of all metrics.
type MetricsSnapshot ¶
type MetricsSnapshot struct {
TotalCalls int64 `json:"total_calls"`
TotalErrors int64 `json:"total_errors"`
TotalTurns int64 `json:"total_turns"`
ByTool map[string]ToolSnapshot `json:"by_tool"`
}
MetricsSnapshot is a point-in-time view of collected metrics.
Source Files