DocsCommonagent-configRuntimeHooks
Package: @hexos/common

Lifecycle callbacks invoked at key points during agent execution.

Hooks enable observability and side effects without modifying core runtime behavior. All hooks are optional and can be synchronous or async. They are called by AgentRuntime during conversation streaming.

Related: RuntimeConfig registers hooks, AgentContext is passed to agent hooks.

interface RuntimeHooks {
    onAgentStart?: (agentId: string, context: AgentContext) => void | Promise<void>;
    onAgentEnd?: (agentId: string, context: AgentContext) => void | Promise<void>;
    onToolCall?: (toolName: string, args: unknown) => void | Promise<void>;
    onToolResult?: (toolName: string, result: unknown) => void | Promise<void>;
    onHandoff?: (from: string, to: string, reason: string) => void | Promise<void>;
    onError?: (error: Error, context: AgentContext) => void | Promise<void>;
}

onAgentStart

(agentId: string, context: AgentContext) => void | Promise

onAgentEnd

(agentId: string, context: AgentContext) => void | Promise

onToolCall

(toolName: string, args: unknown) => void | Promise

onToolResult

(toolName: string, result: unknown) => void | Promise

onHandoff

(from: string, to: string, reason: string) => void | Promise

onError

(error: Error, context: AgentContext) => void | Promise
RuntimeConfigAgentMessage