import type { Hooks } from "@scoopika/types";

const hooks = {
	onStart: (info) => console.log(info.run_id),
	onToken: (token) => console.log(token),
	onToolResult: (info) => console.log(info.call)
}

Hooks in Scoopika offer a powerful mechanism for establishing real-time communication channels with agents and boxes. They enable you to react to various events and data streams throughout the agent or box execution process.

​
Available hooks

​
Lifecycle Hooks

onStart
(info: {run_id: string; session_id: string}) => any

Invoked when a new agent or box run starts. In boxes, it fires upon box run initiation.

onError
(info: {healed: boolean; error: string}) => any

Triggered when an error occurs during an agent run. If provided Scoopika will stop throwing errors and It will pass them to this hook instead.

The healed property specifies if the error was auto healed using the Auto healing feature.

onFinish
(response: AgentResponse) => any

Activated upon the completion of an agent run. For boxes, it’s called after each agent within the box finishes its run. Consider using onAgentResponse instead within boxes (explained later).

Reference to AgentResponse

onAgentResponse
(res: {name: string; response: AgentResponse}) => any

This hook, supported in both agents and boxes, is triggered upon the completion of an individual agent run (within a box context). It delivers an object containing the agent’s name and response. This is the recommended way to handle individual agent responses within boxes as opposed to using onFinish.

Reference to AgentResponse

​
Message Streaming Hooks

onToken
(token: string) => any

This hook delivers a stream of tokens (text chunks) generated by the LLM in real-time, for both agents and boxes.

onStream
(stream: StreamMessage) => any

Similar to onToken, but provides additional information like run_id, type (currently always “text”), and the token content itself.

StreamMessage properties:

  • run_id: string.
  • type: "text" | "image". currently only "text" is being used.
  • content: string. the token value.
  • final: boolean. not being used anymore.

​
Tooling Hooks

onToolCall
(call: ToolCall) => any

Invoked whenever an agent calls an external tool before argument validation and tool execution. While it offers early insight, use with caution due to the lack of argument validation at this stage.

Reference to ToolCall

onToolResult
(info: ToolHistory) => any

Activated when an agent calls an external tool after successful tool argument validation and execution. This hook provides details about the tool call and the returned result.

Reference to ToolHistory

​
Box-Specific Hooks

onSelectAgent
(agent: AgentData) => any

Exclusive to boxes, this hook is called when a box selects an agent to handle a specific task based on factors like the run’s message field within the Inputs and the conversation history.

Reference to AgentData

onBoxFinish
(res: {name: string; run: AgentResponse}[]) => any

Exclusive to boxes, this hook fires when the entire box run finalizes. It delivers an array containing the results (name and run response) from each agent executed within the box run.

Reference to AgentResponse

import type { Hooks } from "@scoopika/types";

const hooks = {
	onStart: (info) => console.log(info.run_id),
	onToken: (token) => console.log(token),
	onToolResult: (info) => console.log(info.call)
}

Was this page helpful?

ContextInputAgentResponse