hooks

type AfterLLMHook ¶

type AfterLLMHook func(ctx context.Context, input AfterLLMHookInput) (AfterLLMHookOutput, error)

AfterLLMHook runs after each LLM response is received. Return a modified response or an error to abort the run.

type AfterLLMHookInput ¶

type AfterLLMHookInput struct {
	RunMeta  RunMeta
	Response interfaces.LLMResponse
}

AfterLLMHookInput is the payload passed to AfterLLMHook after an LLM call completes.

type AfterLLMHookOutput ¶

type AfterLLMHookOutput struct {
	Response interfaces.LLMResponse
}

AfterLLMHookOutput is the mutable result returned from AfterLLMHook.

type AfterMemoryLoadHook ¶

type AfterMemoryLoadHook func(ctx context.Context, input AfterMemoryLoadHookInput) (AfterMemoryLoadHookOutput, error)

AfterMemoryLoadHook runs after memory load. Return a modified prompt context or an error to abort the run.

type AfterMemoryLoadHookInput ¶

type AfterMemoryLoadHookInput struct {
	RunMeta RunMeta
	Scope   interfaces.MemoryScope
	Query   string

	// PromptContext is the formatted memory block injected into the LLM system prompt.
	PromptContext string
}

AfterMemoryLoadHookInput is the payload passed to AfterMemoryLoadHook after memories are loaded.

type AfterMemoryLoadHookOutput ¶

type AfterMemoryLoadHookOutput struct {
	PromptContext string
}

AfterMemoryLoadHookOutput is the mutable result returned from AfterMemoryLoadHook.

type AfterMemoryStoreHook ¶

type AfterMemoryStoreHook func(ctx context.Context, input AfterMemoryStoreHookInput) (AfterMemoryStoreHookOutput, error)

AfterMemoryStoreHook runs after memory store. Return an error to abort the run.

type AfterMemoryStoreHookInput ¶

type AfterMemoryStoreHookInput struct {
	RunMeta RunMeta
	Scope   interfaces.MemoryScope
	Record  interfaces.MemoryRecord

	// ID is the record identifier assigned by the backend after a successful store.
	ID string
}

AfterMemoryStoreHookInput is the payload passed to AfterMemoryStoreHook after a memory is stored.

type AfterMemoryStoreHookOutput ¶

type AfterMemoryStoreHookOutput struct{}

AfterMemoryStoreHookOutput is the mutable result returned from AfterMemoryStoreHook. Store has already completed; hooks use input for audit and may abort via error only.

type AfterRetrieveHook ¶

type AfterRetrieveHook func(ctx context.Context, input AfterRetrieveHookInput) (AfterRetrieveHookOutput, error)

AfterRetrieveHook runs after retrieval. Return filtered or re-ranked documents or an error to abort the run.

type AfterRetrieveHookInput ¶

type AfterRetrieveHookInput struct {
	RunMeta       RunMeta
	Query         string
	Mode          types.RetrieverMode
	RetrieverName string
	Documents     []interfaces.Document
}

AfterRetrieveHookInput is the payload passed to AfterRetrieveHook after documents are retrieved.

type AfterRetrieveHookOutput ¶

type AfterRetrieveHookOutput struct {
	Documents []interfaces.Document
}

AfterRetrieveHookOutput is the mutable result returned from AfterRetrieveHook.

type AfterToolHook ¶

type AfterToolHook func(ctx context.Context, input AfterToolHookInput) (AfterToolHookOutput, error)

AfterToolHook runs after a tool executes. Return a modified result or an error to abort the run.

type AfterToolHookInput ¶

type AfterToolHookInput struct {
	RunMeta RunMeta
	Call    ToolCall

	// Content is the serialized tool result passed back to the LLM.
	Content string

	// Err is set when tool execution failed.
	Err error
}

AfterToolHookInput is the payload passed to AfterToolHook after a tool executes.

type AfterToolHookOutput ¶

type AfterToolHookOutput struct {
	Content string
	Err     error
}

AfterToolHookOutput is the mutable result returned from AfterToolHook.

type AgentHooks ¶

type AgentHooks struct {
	// LLM hooks fire on every model call.
	// BeforeLLM — guardrails, PII redaction, prompt injection detection, caching, input validation
	// AfterLLM  — cost tracking, PII scrubbing, fallback model swap, cache store, token budget enforcement
	BeforeLLM []BeforeLLMHook
	AfterLLM  []AfterLLMHook

	// Tool hooks fire for native and MCP tools only, after authorization and approval.
	// BeforeTool — input scrubbing, rate limiting, arg mutation
	// AfterTool  — result scrubbing, logging, result transformation
	BeforeTool []BeforeToolHook
	AfterTool  []AfterToolHook

	// Retrieve hooks fire for both prefetch and agentic RAG paths.
	// BeforeRetrieve — query rewriting, PII scrubbing, query validation
	// AfterRetrieve  — result filtering, re-ranking, result logging
	BeforeRetrieve []BeforeRetrieveHook
	AfterRetrieve  []AfterRetrieveHook

	// Memory hooks fire on memory read and write operations.
	// BeforeMemoryLoad  — query/load-option mutation; scope is read-only context on input
	// AfterMemoryLoad  — filter or rewrite prompt context injected into the LLM
	// BeforeMemoryStore — scrub PII before persisting, control what gets stored
	// AfterMemoryStore  — audit persisted memories, logging
	BeforeMemoryLoad  []BeforeMemoryLoadHook
	AfterMemoryLoad   []AfterMemoryLoadHook
	BeforeMemoryStore []BeforeMemoryStoreHook
	AfterMemoryStore  []AfterMemoryStoreHook
}

AgentHooks defines middleware hooks that fire at key points in the agent execution lifecycle. Multiple hooks can be registered per execution point and are chained in declaration order. Each hook receives the (possibly modified) output of the previous hook in the chain. Any hook returning an error aborts the remaining chain and halts execution.

Common use cases by category:

• Guardrails and safety: block bad inputs, prompt-injection checks (BeforeLLMHook); output filtering (AfterLLMHook).
• PII and privacy: scrub prompts and responses (BeforeLLMHook, AfterLLMHook); tool args (BeforeToolHook, AfterToolHook); retrieval query and documents (BeforeRetrieveHook, AfterRetrieveHook); memory load (BeforeMemoryLoadHook, AfterMemoryLoadHook) and store (BeforeMemoryStoreHook, AfterMemoryStoreHook).
• Cost and caching: token tracking and budgets (AfterLLMHook, BeforeLLMHook); LLM response cache read/write (BeforeLLMHook, AfterLLMHook).
• Rate limiting and validation: per-tool input scrubbing and rate limits (BeforeToolHook); retrieval query validation (BeforeRetrieveHook).
• Logging and audit: LLM, tool, retrieval, and memory operations (before/after hooks on each area).
• Resilience: model fallback (AfterLLMHook); retrieval retry or re-rank (AfterRetrieveHook).
• Memory control: scope filtering and tenant isolation (BeforeMemoryLoadHook, BeforeMemoryStoreHook); inspect injected context (AfterMemoryLoadHook).

func (h AgentHooks) Merge(other AgentHooks) AgentHooks

type BeforeLLMHook ¶

type BeforeLLMHook func(ctx context.Context, input BeforeLLMHookInput) (BeforeLLMHookOutput, error)

BeforeLLMHook runs before each LLM request is sent. Return a modified request or an error to abort the run.

type BeforeLLMHookInput ¶

type BeforeLLMHookInput struct {
	RunMeta RunMeta
	Request interfaces.LLMRequest
}

BeforeLLMHookInput is the payload passed to BeforeLLMHook before an LLM call.

type BeforeLLMHookOutput ¶

type BeforeLLMHookOutput struct {
	Request interfaces.LLMRequest
}

BeforeLLMHookOutput is the mutable result returned from BeforeLLMHook.

type BeforeMemoryLoadHook ¶

type BeforeMemoryLoadHook func(ctx context.Context, input BeforeMemoryLoadHookInput) (BeforeMemoryLoadHookOutput, error)

BeforeMemoryLoadHook runs before memory load. Return modified query or load options, or an error to abort the run.

type BeforeMemoryLoadHookInput ¶

type BeforeMemoryLoadHookInput struct {
	RunMeta RunMeta
	Scope   interfaces.MemoryScope
	Query   string

	// Limit is the maximum number of memories to return. Zero means backend default.
	Limit int

	// MinScore filters out entries below the given relevance score when Score is applicable.
	MinScore float32

	// Kinds restricts recall to the given memory kinds. Empty means all kinds.
	Kinds []interfaces.MemoryKind
}

BeforeMemoryLoadHookInput is the payload passed to BeforeMemoryLoadHook before memories are loaded.

type BeforeMemoryLoadHookOutput ¶

type BeforeMemoryLoadHookOutput struct {
	Query    string
	Limit    int
	MinScore float32
	Kinds    []interfaces.MemoryKind
}

BeforeMemoryLoadHookOutput is the mutable result returned from BeforeMemoryLoadHook. Only Query and load options may be changed; Scope on input is read-only context.

type BeforeMemoryStoreHook ¶

type BeforeMemoryStoreHook func(ctx context.Context, input BeforeMemoryStoreHookInput) (BeforeMemoryStoreHookOutput, error)

BeforeMemoryStoreHook runs before memory store. Return modified record or upsert ID, or an error to abort the run.

type BeforeMemoryStoreHookInput ¶

type BeforeMemoryStoreHookInput struct {
	RunMeta RunMeta
	Scope   interfaces.MemoryScope
	Record  interfaces.MemoryRecord

	// ID upserts the record when non-empty.
	ID string
}

BeforeMemoryStoreHookInput is the payload passed to BeforeMemoryStoreHook before a memory is stored.

type BeforeMemoryStoreHookOutput ¶

type BeforeMemoryStoreHookOutput struct {
	Record interfaces.MemoryRecord
	ID     string
}

BeforeMemoryStoreHookOutput is the mutable result returned from BeforeMemoryStoreHook. Only Record and ID may be changed; Scope on input is read-only context.

type BeforeRetrieveHook ¶

type BeforeRetrieveHook func(ctx context.Context, input BeforeRetrieveHookInput) (BeforeRetrieveHookOutput, error)

BeforeRetrieveHook runs before retrieval. Return a modified query or an error to abort the run.

type BeforeRetrieveHookInput ¶

type BeforeRetrieveHookInput struct {
	RunMeta RunMeta
	Query   string
	Mode    types.RetrieverMode

	// RetrieverName is the target retriever when agentic; empty when prefetch runs all configured retrievers.
	RetrieverName string
}

BeforeRetrieveHookInput is the payload passed to BeforeRetrieveHook before a retrieval runs.

type BeforeRetrieveHookOutput ¶

type BeforeRetrieveHookOutput struct {
	Query string
}

BeforeRetrieveHookOutput is the mutable result returned from BeforeRetrieveHook. Only Query may be changed; Mode and RetrieverName on input are read-only context.

type BeforeToolHook ¶

type BeforeToolHook func(ctx context.Context, input BeforeToolHookInput) (BeforeToolHookOutput, error)

BeforeToolHook runs immediately before tool.Execute for native and MCP tools, after programmatic authorization and interactive approval have succeeded. Return modified args or an error to abort the run. Not a substitute for the SDK's tool authorization or approval mechanisms.

type BeforeToolHookInput ¶

type BeforeToolHookInput struct {
	RunMeta RunMeta
	Call    ToolCall
}

BeforeToolHookInput is the payload passed to BeforeToolHook before a tool executes.

type BeforeToolHookOutput ¶

type BeforeToolHookOutput struct {
	Args map[string]any
}

BeforeToolHookOutput is the mutable result returned from BeforeToolHook. Only Args may be changed; identity fields on BeforeToolHookInput.Call are read-only context.

type HookGroup ¶

type HookGroup struct {
	// Name is the unique hook group identifier used for Temporal fingerprinting and [RunMeta].
	Name string

	// Hooks are the middleware functions in this group.
	Hooks AgentHooks
}

HookGroup is a named set of middleware hooks registered via github.com/agenticenv/agent-sdk-go/pkg/agent.WithHooks.

type MemoryLoadCall ¶

type MemoryLoadCall struct {
	Scope    interfaces.MemoryScope
	Query    string
	Limit    int
	MinScore float32
	Kinds    []interfaces.MemoryKind
}

MemoryLoadCall is the resolved memory load invocation used by the runtime hook runner.

func RunBeforeMemoryLoad(ctx context.Context, groups []HookGroup, meta RunMeta, call MemoryLoadCall) (MemoryLoadCall, error)

type MemoryStoreCall ¶

type MemoryStoreCall struct {
	Scope  interfaces.MemoryScope
	Record interfaces.MemoryRecord
	ID     string
}

MemoryStoreCall is the resolved memory store invocation used by the runtime hook runner.

func RunBeforeMemoryStore(ctx context.Context, groups []HookGroup, meta RunMeta, call MemoryStoreCall) (MemoryStoreCall, error)

type RetrieveCall ¶

type RetrieveCall struct {
	Query         string
	Mode          types.RetrieverMode
	RetrieverName string
}

RetrieveCall is the resolved retrieval invocation used by the runtime hook runner.

func RunBeforeRetrieve(ctx context.Context, groups []HookGroup, meta RunMeta, call RetrieveCall) (RetrieveCall, error)

type RunMeta ¶

type RunMeta struct {
	// RunID is the stable identifier for the current agent run.
	RunID string

	// Iteration is the zero-based LLM loop round (0 for the first model call).
	Iteration int

	// HooksGroup is the [github.com/agenticenv/agent-sdk-go/pkg/agent.WithHooks] group name for the
	// hook currently executing. The runtime sets this from the validated group name when firing hooks.
	HooksGroup string
}

RunMeta carries read-only execution context shared across hooks in a run. Hooks must not modify RunMeta; the runtime populates it when firing hooks.

type ToolCall ¶

type ToolCall struct {
	// ID is the tool call identifier from the LLM; used to match tool results in the conversation.
	ID string

	// Name is the tool identifier the LLM selected.
	Name string

	// DisplayName is the human-readable tool name when available.
	DisplayName string

	// Kind classifies the tool implementation (native, MCP, sub-agent, etc.).
	Kind types.ToolKind

	// Args are the arguments the LLM produced for this invocation.
	Args map[string]any
}

ToolCall is the resolved tool invocation passed to tool hooks.

func RunBeforeTool(ctx context.Context, groups []HookGroup, meta RunMeta, call ToolCall) (ToolCall, error)